Driver Management

/**
 * Construct a new Neo4j Driver. This is your main entry point for this library.
 * @param url - The URL for the Neo4j database, supports neo4j://, neo4j+s://, neo4j+ssc://, bolt://, bolt+s://, bolt+ssc:// schemes
 * @param authToken - Authentication credentials or auth token manager
 * @param config - Configuration object for driver behavior
 * @returns Driver instance for database operations
 */
function driver(
  url: string,
  authToken?: AuthToken | AuthTokenManager,
  config?: Config
): Driver;

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

// Basic connection
const neo4jDriver = driver(
  "neo4j://localhost:7687",
  auth.basic("neo4j", "password")
);

// With configuration
const configuredDriver = driver(
  "neo4j://localhost:7687",
  auth.basic("neo4j", "password"),
  {
    maxConnectionLifetime: 3600000, // 1 hour
    maxConnectionPoolSize: 50,
    connectionAcquisitionTimeout: 60000,
    encrypted: "ENCRYPTION_ON",
    trust: "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES"
  }
);

// Using cluster endpoint
const clusterDriver = driver(
  "neo4j://cluster.example.com:7687",
  auth.basic("neo4j", "password")
);

/**
 * Verifies if the driver can reach a server at the given url.
 * @experimental
 * @param url - The URL for the Neo4j database
 * @param config - Optional configuration object (logging only)
 * @returns Promise that resolves to true when server is reachable
 * @throws Error when the server is not reachable or the url is invalid
 */
function hasReachableServer(
  url: string,
  config?: Pick<Config, 'logging'>
): Promise<true>;

import { hasReachableServer } from "neo4j-driver";

try {
  await hasReachableServer("neo4j://localhost:7687");
  console.log("Server is reachable");
} catch (error) {
  console.error("Server is not reachable:", error.message);
}

interface Driver {
  /** Create a new session with optional configuration */
  session(config?: SessionConfig): Session;
  
  /** Create a new reactive session with optional configuration */
  rxSession(config?: SessionConfig): RxSession;
  
  /** Get information about the Neo4j server */
  getServerInfo(): Promise<ServerInfo>;
  
  /** Check if the driver supports multi-database functionality */
  supportsMultiDb(): Promise<boolean>;
  
  /** Check if the driver is encrypted */
  isEncrypted(): boolean;
  
  /** Verify connectivity and return negotiated protocol version */
  verifyConnectivity(config?: { database?: string }): Promise<ServerInfo>;
  
  /** Get the negotiated protocol version without authentication */
  getNegotiatedProtocolVersion(): Promise<number>;
  
  /** Close the driver and all associated resources */
  close(): Promise<void>;
}

interface Config {
  /** Encryption level for connections */
  encrypted?: EncryptionLevel;
  
  /** Trust strategy for TLS certificates */
  trust?: TrustStrategy;
  
  /** List of trusted certificates for custom CA */
  trustedCertificates?: string[];
  
  /** Known hosts file path for certificate verification */
  knownHosts?: string;
  
  /** Maximum lifetime of pooled connections in milliseconds */
  maxConnectionLifetime?: number;
  
  /** Maximum number of connections in the pool */
  maxConnectionPoolSize?: number;
  
  /** Timeout for acquiring connections from pool in milliseconds */
  connectionAcquisitionTimeout?: number;
  
  /** Disable automatic conversion to native JavaScript numbers */
  disableLosslessIntegers?: boolean;
  
  /** Custom logging configuration */
  logging?: LoggingConfig;
  
  /** Custom address resolver function */
  resolver?: (address: string) => string[] | Promise<string[]>;
  
  /** Custom user agent string */
  userAgent?: string;
  
  /** Bolt agent metadata */
  boltAgent?: Record<string, any>;
  
  /** Global notification filtering */
  notificationFilter?: NotificationFilter;
  
  /** Disable telemetry reporting */
  telemetryDisabled?: boolean;
  
  /** Client certificate for mutual TLS */
  clientCertificate?: ClientCertificate | ClientCertificateProvider;
}

type EncryptionLevel = "ENCRYPTION_ON" | "ENCRYPTION_OFF";
type TrustStrategy = "TRUST_ALL_CERTIFICATES" | "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES";

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

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

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

const neo4jDriver = driver(
  "neo4j://localhost:7687",
  auth.basic("neo4j", "password"),
  {
    logging: logging.console("DEBUG"),
    maxConnectionPoolSize: 100,
    connectionAcquisitionTimeout: 60000
  }
);

interface ServerInfo {
  address: string;
  agent: string;
  protocolVersion: number;
}