The Neo4j Type System

Integers

Due to a discrepancy between integers in JavaScript and the Neo4j type system, we need to take extra care when working with integers in the Neo4j JavaScript Driver.

The Neo4j type system uses 64-bit signed integer values (with a range of -(264- 1) and (263- 1)) while JavaScript can only safely represent integers between -(253- 1) (Number.MIN_SAFE_INTEGER) and 253- 1 (Number.MAX_SAFE_INTEGER).

To conform with the Neo4j type system, the driver will not automatically convert to JavaScript integers. Instead, the driver will convert integers to a float to ensure no data is lost.

The driver provides an Integer type and an int() function for sending and receiving integers with neo4j.

The Driver will convert any integer values it receives into an instance of an Integer class. The Integer class has a toNumber() method which can be called to safely convert the value back into a JavaScript number.

If the number is outside of the valid range, it will be returned as a string.

// import { int, isInt } from 'neo4j-driver'

// Convert a JavaScript 'number' into a Neo4j Integer
const thisYear = int(2022)

// Check if a value is a Neo4j integer
console.log(isInt(thisYear)) // true

// Convert the Neo4j integer into a JavaScript number
console.log(thisYear.toNumber()) // 2022

We make use of these functions often throughout this course.

Nodes & Relationships

Nodes and Relationships are both returned as similar classes.

As an example, let’s take the following code snippet:

// Execute a query within a read transaction
const res = await session.executeRead(tx => tx.run(`
  MATCH path = (person:Person)-[actedIn:ACTED_IN]->(movie:Movie)
  RETURN path, person, actedIn, movie
  LIMIT 1
`))

// Get the first row
const row = res.records[0]

The query will return one row for each :Person and :Movie node with an :ACTED_IN relationship between them.

const movie = row.get('movie')

person.elementId // (1)
person.labels // (2)
person.properties // (3)

const actedIn = row.get('actedIn')

actedIn.elementId // (1)
actedIn.type // (2)
actedIn.properties // (3)
actedIn.startNodeElementId // (4)
actedIn.endNodeElementId // (5)

const path = row.get('path')

path.start // (1)
path.end // (2)
path.length // (3)
path.segments // (4)

path.segments.forEach(segment => {
  console.log(segment.start)
  console.log(segment.end)
  console.log(segment.relationship)
})

Temporal Types

The Temporal types used in the Cypher type system are also handled differently. The driver exports helper functions to assist in checking the type.

Each type has a toString() method that can be used in conjunction with Date.parse() in JavaScript to convert the Cypher date into a native Date object.

// import { isDateTime, isDate } from 'neo4j-driver'

// Convert a native Date into a Neo4j DateTime
const now = new Date()
const createdAt = DateTime.fromStandardDate(now)

console.log(isDateTime(createdAt)) // true
console.log(isDate(createdAt)) // false

// Convert a Neo4j DateTime back into a native Date
const dateNumber = Date.parse(createdAt.toString())
const nativeDate = new Date(dateNumber)

Spatial Types

Cypher has built-in support for handling spatial values (points), and the underlying database supports storing these point values as properties on nodes and relationships.

import { Point, isPoint } from 'neo4j-driver'

const london = new Point(-0.118092, 51.509865)
const shard = new Point(-0.086500, 51.504501, 310) // 310m high

const cartesian2d = new Point(10, 5)
const cartesian3d = new Point(10, 5, 20)

console.log(london) // Point({srid:4326, x:-0.118092, y:51.509865})
console.log(shard) // Point({srid:4979, x:-0.0865, y:51.504501, z:310})

console.log(catesian2d) // Point({srid:7203, x:5, y:10})
console.log(catesian3d) // Point({srid:9157, x:5, y:10, z:20})

console.log(isPoint(london)) // true
console.log(isPoint('string')) // false

WITH point({x: 1, y:1}) AS one,
     point({x: 10, y: 10}) AS two

RETURN point.distance(one, two) // 12.727922061357855

Converting these values en masse

There may be times when you need to convert many Neo4j types back into native JavaScript types. For example, when retrieving a set of properties.

For this purpose, We have added a utility function to src/utils.js, which, when given an Object of properties, will iterate through the keys and, where appropriate, convert the value to a native JavaScript value. This function is called toNativeTypes().

/**
 * Convert Neo4j Properties back into JavaScript types
 *
 * @param {Record<string, any>} properties
 * @return {Record<string, any>}
 */
export function toNativeTypes(properties) {
  return Object.fromEntries(Object.keys(properties).map((key) => {
    let value = valueToNativeType(properties[key])

    return [ key, value ]
  }))
}

/**
 * Convert an individual value to its JavaScript equivalent
 *
 * @param {any} value
 * @returns {any}
 */
function valueToNativeType(value) {
  if ( Array.isArray(value) ) {
    value = value.map(innerValue => valueToNativeType(innerValue))
  }
  else if ( isInt(value) ) {
    value = value.toNumber()
  }
  else if (
    isDate(value) ||
    isDateTime(value) ||
    isTime(value) ||
    isLocalDateTime(value) ||
    isLocalTime(value) ||
    isDuration(value)
  ) {
    value = value.toString()
  }
  else if (typeof value === 'object' && value !== undefined  && value !== null) {
    value = toNativeTypes(value)
  }

  return value
}

The function is recursive and will handle nested objects and arrays.

Check Your Understanding