0
# Neo4j Driver
1

2
The Neo4j JavaScript driver provides the official client for connecting to and interacting with Neo4j graph databases. It offers a comprehensive API for executing Cypher queries, managing database sessions and transactions, with support for both callback and reactive programming patterns through RxJS integration.
3

4
## Package Information
5

6
- **Package Name**: neo4j-driver
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install neo4j-driver`
10

11
## Core Imports
12

13
```typescript
14
import neo4j from "neo4j-driver";
15
```
16

17
Named imports:
18

19
```typescript
20
import { driver, auth, types, session } from "neo4j-driver";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const neo4j = require("neo4j-driver");
27
// or
28
const { driver, auth, types, session } = require("neo4j-driver");
29
```
30

31
## Basic Usage
32

33
```typescript
34
import { driver, auth } from "neo4j-driver";
35

36
// Create driver instance
37
const neo4jDriver = driver(
38
  "neo4j://localhost:7687",
39
  auth.basic("username", "password")
40
);
41

42
// Create session and run query
43
const session = neo4jDriver.session();
44
try {
45
  const result = await session.run(
46
    "CREATE (p:Person {name: $name}) RETURN p",
47
    { name: "Alice" }
48
  );
49
  
50
  result.records.forEach(record => {
51
    const person = record.get("p");
52
    console.log(person.properties.name);
53
  });
54
} finally {
55
  await session.close();
56
}
57

58
// Close driver
59
await neo4jDriver.close();
60
```
61

62
## Architecture
63

64
Neo4j Driver is built around several key components:
65

66
- **Driver**: Main entry point managing connection pools and providing sessions
67
- **Session Management**: Standard and reactive sessions for query execution
68
- **Transaction Management**: Explicit transactions and auto-managed transactions with retry logic
69
- **Result Handling**: Streaming and eager result processing with comprehensive metadata
70
- **Data Types**: Native JavaScript representations of Neo4j graph and temporal types
71
- **Authentication**: Multiple auth methods including basic, Kerberos, and custom tokens
72
- **Connection Management**: Automatic routing, load balancing, and connection pooling
73

74
## Capabilities
75

76
### Driver Management
77

78
Core driver creation and connection management functionality for establishing and maintaining database connections.
79

80
```typescript { .api }
81
function driver(
82
  url: string,
83
  authToken?: AuthToken | AuthTokenManager,
84
  config?: Config
85
): Driver;
86

87
function hasReachableServer(
88
  url: string,
89
  config?: Pick<Config, 'logging'>
90
): Promise<true>;
91
```
92

93
[Driver Management](./driver-management.md)
94

95
### Session Operations
96

97
Session management for executing queries and managing database interactions with support for read/write modes and transaction handling.
98

99
```typescript { .api }
100
interface Driver {
101
  session(config?: SessionConfig): Session;
102
  rxSession(config?: SessionConfig): RxSession;
103
  close(): Promise<void>;
104
}
105

106
interface Session {
107
  run(query: string, parameters?: Parameters): Promise<Result>;
108
  beginTransaction(config?: TransactionConfig): Promise<Transaction>;
109
  executeRead<T>(work: (tx: ManagedTransaction) => Promise<T>): Promise<T>;
110
  executeWrite<T>(work: (tx: ManagedTransaction) => Promise<T>): Promise<T>;
111
  close(): Promise<void>;
112
}
113
```
114

115
[Session Operations](./session-operations.md)
116

117
### Transaction Management
118

119
Transaction handling including explicit transactions and managed transactions with automatic retry logic for robust database operations.
120

121
```typescript { .api }
122
interface Transaction {
123
  run(query: string, parameters?: Parameters): Promise<Result>;
124
  commit(): Promise<void>;
125
  rollback(): Promise<void>;
126
  isOpen(): boolean;
127
}
128

129
interface ManagedTransaction {
130
  run(query: string, parameters?: Parameters): Promise<Result>;
131
}
132
```
133

134
[Transaction Management](./transaction-management.md)
135

136
### Reactive Programming
137

138
RxJS-based reactive API for streaming query results and handling large datasets with backpressure support.
139

140
```typescript { .api }
141
interface RxSession {
142
  run(query: string, parameters?: Parameters): RxResult;
143
  beginTransaction(config?: TransactionConfig): Observable<RxTransaction>;
144
  executeRead<T>(work: (tx: RxManagedTransaction) => Observable<T>): Observable<T>;
145
  executeWrite<T>(work: (tx: RxManagedTransaction) => Observable<T>): Observable<T>;
146
  close(): Observable<void>;
147
}
148

149
interface RxResult {
150
  keys(): Observable<string[]>;
151
  records(): Observable<Record>;
152
  consume(): Observable<ResultSummary>;
153
}
154
```
155

156
[Reactive Programming](./reactive-programming.md)
157

158
### Graph Data Types
159

160
Neo4j graph data types including nodes, relationships, and paths with comprehensive type checking utilities.
161

162
```typescript { .api }
163
interface Node {
164
  identity: Integer;
165
  labels: string[];
166
  properties: Record<string, any>;
167
}
168

169
interface Relationship {
170
  identity: Integer;
171
  start: Integer;
172
  end: Integer;
173
  type: string;
174
  properties: Record<string, any>;
175
}
176

177
interface Path {
178
  start: Node;
179
  end: Node;
180
  length: number;
181
  segments: PathSegment[];
182
  nodes: Node[];
183
  relationships: Relationship[];
184
}
185
```
186

187
[Graph Data Types](./graph-types.md)
188

189
### Temporal Data Types
190

191
Neo4j temporal data types including dates, times, and durations with timezone support and comprehensive type checking.
192

193
```typescript { .api }
194
interface Date {
195
  year: Integer;
196
  month: Integer;
197
  day: Integer;
198
  toString(): string;
199
}
200

201
interface DateTime {
202
  year: Integer;
203
  month: Integer;
204
  day: Integer;
205
  hour: Integer;
206
  minute: Integer;
207
  second: Integer;
208
  nanosecond: Integer;
209
  timeZoneOffsetSeconds?: Integer;
210
  timeZoneId?: string;
211
}
212

213
interface Duration {
214
  months: Integer;
215
  days: Integer;
216
  seconds: Integer;
217
  nanoseconds: Integer;
218
}
219
```
220

221
[Temporal Data Types](./temporal-types.md)
222

223
### Authentication
224

225
Comprehensive authentication system supporting basic, Kerberos, bearer token, and custom authentication methods.
226

227
```typescript { .api }
228
interface AuthToken {
229
  scheme: string;
230
  principal: string;
231
  credentials: string;
232
  realm?: string;
233
  parameters?: Record<string, any>;
234
}
235

236
declare const auth: {
237
  basic(username: string, password: string, realm?: string): AuthToken;
238
  kerberos(base64EncodedTicket: string): AuthToken;
239
  bearer(base64EncodedToken: string): AuthToken;
240
  custom(
241
    principal: string,
242
    credentials: string,
243
    realm: string,
244
    scheme: string,
245
    parameters?: Parameters
246
  ): AuthToken;
247
};
248
```
249

250
[Authentication](./authentication.md)
251

252
### Error Handling
253

254
Comprehensive error handling with retryable error detection and detailed error information for robust application development.
255

256
```typescript { .api }
257
class Neo4jError extends Error {
258
  code: string;
259
  constructor(message: string, code?: string);
260
}
261

262
function isRetryableError(error: any): boolean;
263

264
declare const error: {
265
  SERVICE_UNAVAILABLE: string;
266
  SESSION_EXPIRED: string;
267
  PROTOCOL_ERROR: string;
268
};
269
```
270

271
[Error Handling](./error-handling.md)
272

273
## Types
274

275
### Core Configuration Types
276

277
```typescript { .api }
278
interface Config {
279
  encrypted?: EncryptionLevel;
280
  trust?: TrustStrategy;
281
  trustedCertificates?: string[];
282
  knownHosts?: string;
283
  maxConnectionLifetime?: number;
284
  maxConnectionPoolSize?: number;
285
  connectionAcquisitionTimeout?: number;
286
  disableLosslessIntegers?: boolean;
287
  logging?: LoggingConfig;
288
  resolver?: (address: string) => string[] | Promise<string[]>;
289
  userAgent?: string;
290
  boltAgent?: Record<string, any>;
291
  notificationFilter?: NotificationFilter;
292
  telemetryDisabled?: boolean;
293
  clientCertificate?: ClientCertificate | ClientCertificateProvider;
294
}
295

296
interface SessionConfig {
297
  defaultAccessMode?: SessionMode;
298
  bookmarks?: string | string[] | Bookmarks;
299
  database?: string;
300
  impersonatedUser?: string;
301
  bookmarkManager?: BookmarkManager;
302
  notificationFilter?: NotificationFilter;
303
  auth?: AuthToken | AuthTokenManager;
304
}
305

306
interface TransactionConfig {
307
  timeout?: number;
308
  metadata?: Record<string, any>;
309
}
310

311
type EncryptionLevel = "ENCRYPTION_ON" | "ENCRYPTION_OFF";
312
type TrustStrategy = "TRUST_ALL_CERTIFICATES" | "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES";
313
type SessionMode = "READ" | "WRITE";
314
```
315

316
### Additional Utilities
317

318
```typescript { .api }
319
/** Bookmark manager factory and utilities */
320
declare const bookmarkManager: {
321
  memory(): BookmarkManager;
322
};
323

324
/** Result transformation utilities */
325
declare const resultTransformers: {
326
  eagerTransformer(): ResultTransformer;
327
};
328

329
/** Routing control constants */
330
declare const routing: {
331
  READ: RoutingControl;
332
  WRITE: RoutingControl;
333
};
334

335
/** Client certificate provider utilities */
336
declare const clientCertificateProviders: ClientCertificateProviders;
337

338
/** Notification category constants */
339
declare const notificationCategory: NotificationCategory;
340

341
/** Notification classification constants */
342
declare const notificationClassification: NotificationClassification;
343

344
/** Notification severity level constants */
345
declare const notificationSeverityLevel: NotificationSeverityLevel;
346

347
/** Notification filter utilities for disabled categories */
348
declare const notificationFilterDisabledCategory: NotificationFilterDisabledCategory;
349

350
/** Notification filter utilities for disabled classifications */
351
declare const notificationFilterDisabledClassification: NotificationFilterDisabledClassification;
352

353
/** Notification filter utilities for minimum severity levels */
354
declare const notificationFilterMinimumSeverityLevel: NotificationFilterMinimumSeverityLevel;
355

356
/** Type constructors collection */
357
declare const types: {
358
  Node: typeof Node;
359
  Relationship: typeof Relationship;
360
  UnboundRelationship: typeof UnboundRelationship;
361
  PathSegment: typeof PathSegment;
362
  Path: typeof Path;
363
  Result: typeof Result;
364
  EagerResult: typeof EagerResult;
365
  ResultSummary: typeof ResultSummary;
366
  Record: typeof Record;
367
  Point: typeof Point;
368
  Date: typeof Date;
369
  DateTime: typeof DateTime;
370
  Duration: typeof Duration;
371
  LocalDateTime: typeof LocalDateTime;
372
  LocalTime: typeof LocalTime;
373
  Time: typeof Time;
374
  Integer: typeof Integer;
375
};
376
```
377

378
### Integer Utilities
379

380
```typescript { .api }
381
/** Create Integer from number or string */
382
function int(value: number | string): Integer;
383

384
/** Check if value is an Integer instance */
385
function isInt(value: any): value is Integer;
386

387
/** Integer utility functions */
388
declare const integer: {
389
  toNumber(value: Integer): number;
390
  toString(value: Integer): string;
391
  inSafeRange(value: Integer): boolean;
392
};
393

394
/** Spatial utility functions */
395
declare const spatial: {
396
  isPoint(value: any): value is Point;
397
};
398

399
/** Temporal utility functions */
400
declare const temporal: {
401
  isDate(value: any): value is Date;
402
  isDateTime(value: any): value is DateTime;
403
  isLocalDateTime(value: any): value is LocalDateTime;
404
  isTime(value: any): value is Time;
405
  isLocalTime(value: any): value is LocalTime;
406
  isDuration(value: any): value is Duration;
407
};
408

409
/** Graph utility functions */
410
declare const graph: {
411
  isNode(value: any): value is Node;
412
  isRelationship(value: any): value is Relationship;
413
  isUnboundRelationship(value: any): value is UnboundRelationship;
414
  isPath(value: any): value is Path;
415
  isPathSegment(value: any): value is PathSegment;
416
};
417

418
/** Logging configuration utilities */
419
declare const logging: {
420
  console: (level?: "DEBUG" | "INFO" | "WARN" | "ERROR") => LoggingConfig;
421
};
422

423
/** Authentication token manager utilities */
424
declare const authTokenManagers: {
425
  staticAuthTokenManager: (options: { authToken: AuthToken }) => AuthTokenManager;
426
};
427

428
/** Session access mode constants */
429
declare const session: {
430
  READ: SessionMode;
431
  WRITE: SessionMode;
432
};
433
```
434

435
### Utility Types
436

437
```typescript { .api }
438
type Parameters = Record<string, any>;
439

440
interface LoggingConfig {
441
  level: "DEBUG" | "INFO" | "WARN" | "ERROR";
442
  logger: (level: string, message: string) => void;
443
}
444

445
interface Integer {
446
  low: number;
447
  high: number;
448
  toString(): string;
449
  toNumber(): number;
450
  equals(other: Integer): boolean;
451
  compare(other: Integer): number;
452
}
453
```