or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mddriver-management.mderror-handling.mdgraph-types.mdindex.mdreactive-programming.mdsession-operations.mdtemporal-types.mdtransaction-management.md
tile.json

tessl/npm-neo4j-driver

The official Neo4j driver for JavaScript applications, enabling connection to and interaction with Neo4j graph databases.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/neo4j-driver@5.28.x

To install, run

npx @tessl/cli install tessl/npm-neo4j-driver@5.28.0

index.mddocs/

Neo4j Driver

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.

Package Information

  • Package Name: neo4j-driver
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install neo4j-driver

Core Imports

import neo4j from "neo4j-driver";

Named imports:

import { driver, auth, types, session } from "neo4j-driver";

For CommonJS:

const neo4j = require("neo4j-driver");
// or
const { driver, auth, types, session } = require("neo4j-driver");

Basic Usage

import { driver, auth } from "neo4j-driver";

// Create driver instance
const neo4jDriver = driver(
  "neo4j://localhost:7687",
  auth.basic("username", "password")
);

// Create session and run query
const session = neo4jDriver.session();
try {
  const result = await session.run(
    "CREATE (p:Person {name: $name}) RETURN p",
    { name: "Alice" }
  );
  
  result.records.forEach(record => {
    const person = record.get("p");
    console.log(person.properties.name);
  });
} finally {
  await session.close();
}

// Close driver
await neo4jDriver.close();

Architecture

Neo4j Driver is built around several key components:

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

Capabilities

Driver Management

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

function driver(
  url: string,
  authToken?: AuthToken | AuthTokenManager,
  config?: Config
): Driver;

function hasReachableServer(
  url: string,
  config?: Pick<Config, 'logging'>
): Promise<true>;

Driver Management

Session Operations

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

interface Driver {
  session(config?: SessionConfig): Session;
  rxSession(config?: SessionConfig): RxSession;
  close(): Promise<void>;
}

interface Session {
  run(query: string, parameters?: Parameters): Promise<Result>;
  beginTransaction(config?: TransactionConfig): Promise<Transaction>;
  executeRead<T>(work: (tx: ManagedTransaction) => Promise<T>): Promise<T>;
  executeWrite<T>(work: (tx: ManagedTransaction) => Promise<T>): Promise<T>;
  close(): Promise<void>;
}

Session Operations

Transaction Management

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

interface Transaction {
  run(query: string, parameters?: Parameters): Promise<Result>;
  commit(): Promise<void>;
  rollback(): Promise<void>;
  isOpen(): boolean;
}

interface ManagedTransaction {
  run(query: string, parameters?: Parameters): Promise<Result>;
}

Transaction Management

Reactive Programming

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

interface RxSession {
  run(query: string, parameters?: Parameters): RxResult;
  beginTransaction(config?: TransactionConfig): Observable<RxTransaction>;
  executeRead<T>(work: (tx: RxManagedTransaction) => Observable<T>): Observable<T>;
  executeWrite<T>(work: (tx: RxManagedTransaction) => Observable<T>): Observable<T>;
  close(): Observable<void>;
}

interface RxResult {
  keys(): Observable<string[]>;
  records(): Observable<Record>;
  consume(): Observable<ResultSummary>;
}

Reactive Programming

Graph Data Types

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

interface Node {
  identity: Integer;
  labels: string[];
  properties: Record<string, any>;
}

interface Relationship {
  identity: Integer;
  start: Integer;
  end: Integer;
  type: string;
  properties: Record<string, any>;
}

interface Path {
  start: Node;
  end: Node;
  length: number;
  segments: PathSegment[];
  nodes: Node[];
  relationships: Relationship[];
}

Graph Data Types

Temporal Data Types

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

interface Date {
  year: Integer;
  month: Integer;
  day: Integer;
  toString(): string;
}

interface DateTime {
  year: Integer;
  month: Integer;
  day: Integer;
  hour: Integer;
  minute: Integer;
  second: Integer;
  nanosecond: Integer;
  timeZoneOffsetSeconds?: Integer;
  timeZoneId?: string;
}

interface Duration {
  months: Integer;
  days: Integer;
  seconds: Integer;
  nanoseconds: Integer;
}

Temporal Data Types

Authentication

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

interface AuthToken {
  scheme: string;
  principal: string;
  credentials: string;
  realm?: string;
  parameters?: Record<string, any>;
}

declare const auth: {
  basic(username: string, password: string, realm?: string): AuthToken;
  kerberos(base64EncodedTicket: string): AuthToken;
  bearer(base64EncodedToken: string): AuthToken;
  custom(
    principal: string,
    credentials: string,
    realm: string,
    scheme: string,
    parameters?: Parameters
  ): AuthToken;
};

Authentication

Error Handling

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

class Neo4jError extends Error {
  code: string;
  constructor(message: string, code?: string);
}

function isRetryableError(error: any): boolean;

declare const error: {
  SERVICE_UNAVAILABLE: string;
  SESSION_EXPIRED: string;
  PROTOCOL_ERROR: string;
};

Error Handling

Types

Core Configuration Types

interface Config {
  encrypted?: EncryptionLevel;
  trust?: TrustStrategy;
  trustedCertificates?: string[];
  knownHosts?: string;
  maxConnectionLifetime?: number;
  maxConnectionPoolSize?: number;
  connectionAcquisitionTimeout?: number;
  disableLosslessIntegers?: boolean;
  logging?: LoggingConfig;
  resolver?: (address: string) => string[] | Promise<string[]>;
  userAgent?: string;
  boltAgent?: Record<string, any>;
  notificationFilter?: NotificationFilter;
  telemetryDisabled?: boolean;
  clientCertificate?: ClientCertificate | ClientCertificateProvider;
}

interface SessionConfig {
  defaultAccessMode?: SessionMode;
  bookmarks?: string | string[] | Bookmarks;
  database?: string;
  impersonatedUser?: string;
  bookmarkManager?: BookmarkManager;
  notificationFilter?: NotificationFilter;
  auth?: AuthToken | AuthTokenManager;
}

interface TransactionConfig {
  timeout?: number;
  metadata?: Record<string, any>;
}

type EncryptionLevel = "ENCRYPTION_ON" | "ENCRYPTION_OFF";
type TrustStrategy = "TRUST_ALL_CERTIFICATES" | "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES";
type SessionMode = "READ" | "WRITE";

Additional Utilities

/** Bookmark manager factory and utilities */
declare const bookmarkManager: {
  memory(): BookmarkManager;
};

/** Result transformation utilities */
declare const resultTransformers: {
  eagerTransformer(): ResultTransformer;
};

/** Routing control constants */
declare const routing: {
  READ: RoutingControl;
  WRITE: RoutingControl;
};

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

/** Notification category constants */
declare const notificationCategory: NotificationCategory;

/** Notification classification constants */
declare const notificationClassification: NotificationClassification;

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

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

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

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

/** Type constructors collection */
declare const types: {
  Node: typeof Node;
  Relationship: typeof Relationship;
  UnboundRelationship: typeof UnboundRelationship;
  PathSegment: typeof PathSegment;
  Path: typeof Path;
  Result: typeof Result;
  EagerResult: typeof EagerResult;
  ResultSummary: typeof ResultSummary;
  Record: typeof Record;
  Point: typeof Point;
  Date: typeof Date;
  DateTime: typeof DateTime;
  Duration: typeof Duration;
  LocalDateTime: typeof LocalDateTime;
  LocalTime: typeof LocalTime;
  Time: typeof Time;
  Integer: typeof Integer;
};

Integer Utilities

/** Create Integer from number or string */
function int(value: number | string): Integer;

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

/** Integer utility functions */
declare const integer: {
  toNumber(value: Integer): number;
  toString(value: Integer): string;
  inSafeRange(value: Integer): boolean;
};

/** Spatial utility functions */
declare const spatial: {
  isPoint(value: any): value is Point;
};

/** Temporal utility functions */
declare const temporal: {
  isDate(value: any): value is Date;
  isDateTime(value: any): value is DateTime;
  isLocalDateTime(value: any): value is LocalDateTime;
  isTime(value: any): value is Time;
  isLocalTime(value: any): value is LocalTime;
  isDuration(value: any): value is Duration;
};

/** Graph utility functions */
declare const graph: {
  isNode(value: any): value is Node;
  isRelationship(value: any): value is Relationship;
  isUnboundRelationship(value: any): value is UnboundRelationship;
  isPath(value: any): value is Path;
  isPathSegment(value: any): value is PathSegment;
};

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

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

/** Session access mode constants */
declare const session: {
  READ: SessionMode;
  WRITE: SessionMode;
};

Utility Types

type Parameters = Record<string, any>;

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

interface Integer {
  low: number;
  high: number;
  toString(): string;
  toNumber(): number;
  equals(other: Integer): boolean;
  compare(other: Integer): number;
}