Neo4j JavaScript Driver

The driver supports three ways to consume query results:

1. Promise API: The complete result set is collected before you can act on it. Best for standard async/await workflows.
2. Streaming API (Subscriber): Records are processed lazily as they arrive from the database. This is useful for large result sets to reduce memory overhead. It uses callbacks like onNext, onCompleted, and onError.
3. Reactive API: Uses Observables for a fully reactive stream of data. Best for integration with reactive programming patterns.

// Promise API
session.run('MATCH (n) RETURN n').then(result => {
  result.records.forEach(record => console.log(record.get(0)))
})

// Streaming API
session.run('MATCH (n) RETURN n').subscribe({
  onNext: record => console.log(record.get(0)),
  onCompleted: () => session.close()
})

// Reactive API
rxSession.run('MATCH (n) RETURN n').records().subscribe({
  next: record => console.log(record.get(0))
})

Neo4j uses 64-bit signed integers, which can exceed the safe integer range of JavaScript (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER). To prevent precision loss, the driver uses an internal integer type instead of native JavaScript numbers.

Writing Integers

Any JavaScript number passed as a parameter is treated as a Float. To write an integer, use neo4j.int(). For values outside the safe JavaScript range, pass the value as a string to neo4j.int().

Reading Integers

When reading values, check if they are within the safe range before converting to a native number using neo4j.integer.inSafeRange() and .toNumber(). For large integers, use .toString().

Enabling Native Numbers (Lossy)

You can configure the driver to return native JavaScript numbers for all integers by setting disableLossyIntegers: true in the driver configuration. Warning: This can result in loss of precision for integers outside the safe JavaScript range.

// Writing integers
session.run('CREATE (n {age: $myIntParam})', { myIntParam: neo4j.int(22) });
session.run('CREATE (n {age: $myIntParam})', { myIntParam: neo4j.int('9223372036854775807') });

// Reading integers safely
var smallInteger = neo4j.int(123);
if (neo4j.integer.inSafeRange(smallInteger)) {
  var aNumber = smallInteger.toNumber();
}

// Reading large integers as strings
var largeInteger = neo4j.int('9223372036854775807');
if (!neo4j.integer.inSafeRange(largeInteger)) {
  var integerAsString = largeInteger.toString();
}

// Configuring driver to return native (potentially lossy) numbers
var driver = neo4j.driver(
  'neo4j://localhost',
  neo4j.auth.basic('neo4j', 'password'),
  { disableLossyIntegers: true }
);

Neo4j uses 64-bit signed integers, which can exceed the safe integer range of JavaScript (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER). To prevent precision loss, the driver uses a custom internal integer type.

Writing Integers

Any JavaScript number passed as a parameter is treated as a Float. To write an integer, use neo4j.int():

• Standard: neo4j.int(22)
• Large Integers (via string): neo4j.int('9223372036854775807')

Reading Integers

When reading values, check if they are safe to convert to a native JavaScript number using neo4j.integer.inSafeRange().

• Safe conversion: smallInteger.toNumber()
• Unsafe (use string): largeInteger.toString()

Enabling Native Numbers (Lossy Mode)

You can configure the driver to return native JavaScript numbers instead of custom Integer objects by setting disableLossyIntegers: true. Warning: This can result in loss of precision for integers outside the safe JavaScript range.

// Writing an integer
session.run('CREATE (n {age: $myIntParam})', { myIntParam: neo4j.int(22) });

// Reading an integer safely
var smallInteger = neo4j.int(123);
if (neo4j.integer.inSafeRange(smallInteger)) {
  var aNumber = smallInteger.toNumber();
}

// Configuring driver to use native numbers (potentially lossy)
var driver = neo4j.driver(
  'neo4j://localhost',
  neo4j.auth.basic('neo4j', 'password'),
  { disableLossyIntegers: true }
);

Sessions are used to run Cypher statements. You can acquire either a Regular Session (using Promises/Async-Await) or a Reactive Session (using Observables).

When acquiring a session, you can configure:

• database: The specific database to target.
• defaultAccessMode: Set to neo4j.session.READ or neo4j.session.WRITE.
• bookmarks: An array of bookmarks to ensure causal consistency across sessions.

Important: Always close your sessions when finished.

// Regular Session examples
var session = driver.session() // Default
var session = driver.session({ defaultAccessMode: neo4j.session.READ })
var session = driver.session({ bookmarks: [bookmark1, bookmark2] })
var session = driver.session({ database: 'foo', defaultAccessMode: neo4j.session.WRITE })

// Reactive Session examples
var rxSession = driver.rxSession()
var rxSession = driver.rxSession({ defaultAccessMode: neo4j.session.READ })
var rxSession = driver.rxSession({ bookmarks: [bookmark1, bookmark2] })
var rxSession = driver.rxSession({ database: 'foo', defaultAccessMode: neo4j.session.WRITE })

Testkit is used to run tests against the Javascript Lite Driver. This setup requires Testkit 6, Python3, and Docker.

Setup Steps

1. Clone the Testkit repository: git clone https://github.com/neo4j-drivers/testkit.git
2. Install Python requirements: pip3 install -r requirements.txt inside the Testkit folder.
3. Configure environment variables to point to the driver repository.

Environment Variables

By default, Testkit runs against the full version of the driver.

# 1. Clone Testkit
$ git clone https://github.com/neo4j-drivers/testkit.git

# 2. Install requirements
$ pip3 install -r requirements.txt

# 3. Configure environment
$ export TEST_DRIVER_NAME=javascript
$ export TEST_DRIVER_REPO=<path for the root folder of driver repository>

# To test Lite driver specifically:
$ export TEST_DRIVER_LITE=1

# 4. Run tests
$ python3 main.py