GraphAcademy

Building Neo4j Applications with TypeScript

Neo4j & TypeScript

Installation

The Neo4j JavaScript Driver

The Neo4j JavaScript Driver is available on NPM under the package name neo4j-driver. You can install the Neo4j JavaScript Driver as a dependency by running the following command:

sh
.Installing the neo4j-driver dependency
[source,sh]

npm install neo4j-driver

Importing the Library

The neo4j-driver package exports a neo4j object which contains several helper functions for interacting with Neo4j.

import neo4j from 'neo4j-driver'

Creating a Driver Instance

The most prominent helper function on the neo4j object is the .driver() function, which accepts neo4j credentials and returns a new Driver object.

ts
Creating a Driver Instance
// Create a Driver Instance
const driver = neo4j.driver(
  'neo4j+s://dbhash.databases.neo4j.io', // (1)
  neo4j.auth.basic('neo4j', 'letmein!'), // (2)
  { disableLosslessIntegers: true } // (3)
)

The function expects two arguments;

  1. A Connection URI - for example, neo4j://localhost:7687 or neo4j+s://dbhash.databases.neo4j.io

  2. An authentication token

  3. Optionally, additional driver configuration.

Authentication Types

Neo4j supports four authentication methods, basic authentication (e.g. username and password or LDAP), a base64 encoded Bearer token, a Kerberos token, or a custom authentication token. For more information on these options, visit Authentication and Authorization.

Verifying Connectivity

You can verify that the connection details used during driver instantiation are correct by calling the verifyConnectivity() method.

This function returns a Promise which throws a Neo.ClientError.Security.Unauthorized error if the provided credentials are incorrect.

ts
Verify Connectivity
// Verify Connectivity
await driver.verifyConnectivity()

Sessions

From the Driver object, you will open one or more sessions. A session is a client-side abstraction that borrows underlying TCP connections from a connection pool held by the Driver and uses them to communicate with Neo4j.

Sessions should be considered lightweight and disposable and can be opened and closed at will.

Once you have run all the queries you intend to run within that session, you should call the .close() method to close the session.

Calling the session.close() method releases any connections still held by the session back to the driver pool.

ts
Session Lifecycle
// Open a new session
const session = driver.session()

try {
  // Run a Query
}
catch {
  // Handle any errors
}
finally {
  // Close the session
  await session.close()
}

Running a Sample Query

To run a one-off Cypher query, you can use the session.run() method.

ts
Running a One-off Query
// Execute a Cypher statement in an auto-commit transaction
const res = await session.run(
  `
    MATCH (p:Person)-[:DIRECTED]->(:Movie {title: $title})
    RETURN p.name
  `, // (1)
  { title: 'The Matrix' }, // (2)
  { timeout: 3000 } // (3)
)

The method accepts three arguments:

  1. A string to represent a Cypher statement

  2. Optionally, an object representing query parameters (prefixed in Cypher with $)

  3. A third optional object containing transaction config.

For one-off queries only

If there are any transient errors when running a query, the Driver will not attempt to retry a query when using session.run(). For this reason, these should only be used for one-off queries and not in production.

Processing Results

The res value in the sample above will implement the QueryResult interface. The QueryResult interface guarantees access to the individual records returned by the query through the records property, which contains an array of Record instances.

The Record class has a .get() method, which provides access to the individual values held on that record. For example, to get the (:Person) node from each record, you can write the following code:

ts
Accessing Results
// Get all Person nodes
const people = res.records.map(
  (record: Record) => record.get('p')
)

We will cover result processing in more detail in Lesson 3: Read and Write Transactions.

Closing the Driver

The Driver provides a .close() method. Calling this function will close any open sessions, disconnect all servers, and release any resources still held by the driver.

ts
Running a One-off Query
await driver.close()

Check Your Understanding

Neo4j JavaScript Driver dependency name

What name is the Neo4j JavaScript Driver registered under on NPM?

  • ❏ @neo4j/driver

  • ❏ neo4j

  • ✓ neo4j-driver

  • ❏ neo4j-javascript-driver

Hint

The package is registered on npm as neo4j-driver.

Solution

The package is registered on npm as neo4j-driver.

Summary

In this lesson, you learned the basics of the Neo4j JavaScript Driver, how to install the dependency, create a new Driver instance, and run a sample query.

In the next lesson, you will use this knowledge to create a new Driver instance and run a Cypher statement against a Neo4j Sandbox instance.

Further Reading