Expand Record Object Mapping to allow Parameter Mapping by MaxAake · Pull Request #1362 · neo4j/neo4j-javascript-driver

MaxAake · 2025-11-19T14:17:43Z

This PR provides support for typechecking and automatic conversion of parameters, as well as using the object mapping registry to register mapping strategies for classes. This lets users directly pass objects even with problematic properties that can not be sent over bolt (like functions), by automatically converting them or by omitting them from the mapping strategy.

This is the 2nd half of the Record Object Mapping feature, which is also marked stabilized and taken out of preview in this PR.

Examples

class Obj {
    constructor (obj) {
        this.string = obj?.string ?? 'hi'
        this.number = obj?.number ?? 1
        this.bigint = obj?.bigint ?? BigInt(1)
        this.date = obj?.date ?? "2024-01-01"
        this.localDate = obj?.localDate ?? "2024-01-01"
        this.dateTime = obj?.dateTime ?? new neo4j.DateTime(1, 1, 1, 1, 1, 1, 1, 0)._toUTC()
        this.localDateTime = obj?.localDateTime ?? new neo4j.LocalDateTime(1, 1, 1, 1, 1, 1, 1).toString()
        this.duration = obj?.duration ?? "P1DT5.00007S"
        this.time = obj?.time ?? "10:11:12.13Z"
        this.localTime = obj?.localTime ?? "10:11:12.0001"
        this.list = obj?.list ?? ["hi"]
        this.function = () => "function string" // bolt cannot send functions
        this.node = new neo4j.Node("123", [], {}) // nor can it send nodes
    }
}

const session = driver.session()
const rules = {
    number: neo4j.rule.asNumber(),
    string: neo4j.rule.asString(),
    bigint: neo4j.rule.asBigInt({acceptNumber: true}),
    date: neo4j.rule.asDate({stringify: true}), // this will ensure date is stored as a Date in the DB and retrieved as a string 
    localDate: neo4j.rule.asDate({stringify: true}),
    dateTime: neo4j.rule.asDateTime({stringify: true}),
    localDateTime: neo4j.rule.asLocalDateTime({stringify: true}),
    duration: neo4j.rule.asDuration({stringify: true}),
    time: neo4j.rule.asTime({from: "dob", stringify: true}),
    localTime: neo4j.rule.asLocalTime({stringify: true}),
    list: neo4j.rule.asList({ apply: neo4j.rule.asString() }),
} // not including function and node here will make the driver skip sending them. They could alternatively be converted to a bolt-compatible type.

neo4j.RecordObjectMapping.register(Obj, rules)

// This allows us to use camelCase for our object properties and snake_case for the properties on our node in the DB
neo4j.RecordObjectMapping.translateIdentifiers(neo4j.RecordObjectMapping.getCaseTranslator("snake_case", "camelCase"))

session.run(
  'MERGE (n {string: $string, number: $number, bigint: $bigint, date: $date, local_date: $local_date, date_time: $date_time, local_date_time: $local_date_time, duration: $duration, dob: $dob, local_time: $local_time, list: $list}) RETURN n',
  new Obj(),
  {}
).as({n: {convert: (n) => new Obj(n.as(rules))}})
.then((res) => {
    console.log(res.records[0])
    session.close()
    driver.close()
})

robsdedude

Review part 1. I'll continue next week with the review. I just want to submit my comments to make sure they don't get lost.

packages/core/src/internal/util.ts

packages/core/src/graph-types.ts

packages/core/src/mapping.highlevel.ts

packages/core/src/session.ts

packages/core/src/mapping.highlevel.ts

robsdedude · 2026-02-02T13:29:27Z

packages/core/src/temporal-types.ts

+   * @param {string} str The string to convert
+   * @returns {LocalDateTime<NumberOrInteger>}
+   */
+  static fromString (str: string): LocalDateTime<NumberOrInteger> {


Here's a list of strings that probably should fail, but don't.

'+2026-01-05T15:36:42', '-2026-01-05T15:36:42', '20260-01-05T15:36:42', '2026-001-05T15:36:42',

The latter two are still being accepted.

packages/core/src/temporal-types.ts

packages/core/test/temporal-types.test.ts

MaxAake · 2026-02-13T09:20:13Z

Consider making the optional parameter on the rules also allow for the record to totally lack that key, rather than only allow it to be undefined.

robsdedude

Here goes a first round of comments. Submitting them now so they don't get lost until tomorrow when I shall continue.

robsdedude · 2026-03-09T08:20:20Z

packages/core/src/temporal-types.ts

+   * @param {string} str The string to convert
+   * @returns {Date<NumberOrInteger>}
+   */
+  static fromString (str: string): Date<Integer> {


As far as I can tell, neo4j.Date.fromString("2026-02-31") works just fine and yields a data that doesn't exist: Feb. 31st 2026. Granted, node JS also parses this date fine but wraps the days around into March

> new Date("2026-02-31") 2026-03-03T00:00:00.000Z

I tested round tripping the invalid neo4j.Date via Bolt and it ends up wrapping like nodeJS does locally, too. I'm fairly certain that's because of bolt's encoding of dates using ordinals.

Note that this behavior will likely cause issues when adding/productizing HTTP Query API support because the server will likely not accept "2026-02-31" as a date string.

I realize that the neo4j.Date constructor was not added in this PR, so there not much to be done here besides raising awareness of the quirk and maybe putting a plan in place to fix it in the next major version.

packages/core/src/graph-types.ts

packages/core/src/mapping.highlevel.ts

robsdedude · 2026-03-09T09:21:40Z

packages/core/src/internal/util.ts

 */
 function validateQueryAndParameters (
-  query: string | String | { text: string, parameters?: any },
+  query: string | String | { text: string, parameters?: any, parameterRules?: Rules },


parameterRules missing in doc comment

robsdedude · 2026-03-09T09:21:49Z

packages/core/src/internal/util.ts

+  query: string | String | { text: string, parameters?: any, parameterRules?: Rules },
  parameters?: any,
-  opt?: { skipAsserts: boolean }
+  opt?: { skipAsserts?: boolean, parameterRules?: Rules }


opt missing in doc comment

robsdedude · 2026-03-09T20:11:31Z

packages/core/src/temporal-types.ts

+   * @returns {Time<NumberOrInteger>}
+   */
+  static fromString (str: string): Time<Integer> {
+    const values = String(str.replace(/,/g, '.')).match(/^[T|t]?(\d{2}):?(\d{2})?:?(\d{2})?(\.\d+)?(Z|\+|-)(\d{0,2}):?(\d{0,2}):?(\d{0,2})$/)


I find the timezone offset matching too lenient. Here's a suggested exhaustive list of formats (placeholders with lower case letters - each letter exactly one digit 0-9, other characters are literals):

Z

+hh

+hhmm

+hh:mm

+hh:mm:ss (note: not ISO conform, but the HTTP Query API server as well as the driver itself might still produce it 😬)

-hh

-hhmm

-hh:mm

-hh:mm:ss (note: not ISO conform)

In contrast, the current regex will, among other formats, accept "Z0100", "+123", "+::7", and "-0102:2"

robsdedude · 2026-03-09T20:20:52Z

packages/core/src/temporal-types.ts

+   * @returns {LocalTime<NumberOrInteger>}
+   */
+  static fromString (str: string): LocalTime<Integer> {
+    const values = String(str.replace(/,/g, '.')).match(/^T?(\d{2}):?(\d{2})?:?(\d{2})?(\.\d+)?$/)


If you decide to keep that letters in other Regexes are case-insensitive, this leading T should be too for consistency.

robsdedude · 2026-03-09T20:30:28Z

packages/core/src/temporal-types.ts

+   * @returns {Date<NumberOrInteger>}
+   */
+  static fromString (str: string): Date<Integer> {
+    const values = String(str.replace(/,/g, '.')).match(/^(\d+)-(\d+)-(\d+)$/)


Does not accept negative years.

robsdedude · 2026-03-09T20:30:52Z

packages/core/src/temporal-types.ts

+   * @returns {Date<NumberOrInteger>}
+   */
+  static fromString (str: string): Date<Integer> {
+    const values = String(str.replace(/,/g, '.')).match(/^(\d+)-(\d+)-(\d+)$/)


Dependent on how strict you want this to be:

https://en.wikipedia.org/wiki/ISO_8601#Years

For positive years, this is regex is more lenient that ISO which requires either exactly four digits and no sign XOR more than four digits and a sign.

robsdedude · 2026-03-09T20:32:47Z

packages/core/src/temporal-types.ts

+   * @param {string} str The string to convert
+   * @returns {LocalDateTime<NumberOrInteger>}
+   */
+  static fromString (str: string): LocalDateTime<NumberOrInteger> {


The latter two are still being accepted.

robsdedude · 2026-03-10T07:57:43Z

packages/core/src/temporal-types.ts

  }
 }
+
+function parseTemporalFloat (str: string, field: string, maxLength?: number): number {


Suggested change

function parseTemporalFloat (str: string, field: string, maxLength?: number): number {

function parseTemporalFloat (str: string, field: string): number {

unused parameter (inside function and at all call sites), or should it be used but isn't?

robsdedude · 2026-03-10T07:58:30Z

packages/core/src/temporal-types.ts

 }
+
+function parseTemporalFloat (str: string, field: string, maxLength?: number): number {
+  if (str === undefined || str.length === 0) {


If str can be undefined, shouldn't the signature read str?: string?

robsdedude · 2026-03-10T07:59:10Z

packages/core/src/temporal-types.ts

+}
+
+function parseTemporalInt (str: string, field: string, maxLength?: number): Integer {
+  if (str === undefined || str.length === 0 || str === 'undefined') {


If str can be undefined, shouldn't the signature read str?: string?

robsdedude · 2026-03-10T08:03:02Z

packages/core/src/temporal-types.ts

+  return result
+}
+
+function handleTimeDecimals (hourString: string, minuteString: string, secondString: string, decimalString: string): [Integer, Integer, Integer, Integer] {


Suggested change

function handleTimeDecimals (hourString: string, minuteString: string, secondString: string, decimalString: string): [Integer, Integer, Integer, Integer] {

function handleTimeDecimals (hourString?: string, minuteString?: string, secondString?: string, decimalString?: string): [Integer, Integer, Integer, Integer] {

Either this or get rid of the undefined checks inside the function, me thinks.

robsdedude · 2026-03-10T08:46:14Z

packages/core/src/temporal-types.ts

+  let minutes
+  let seconds
+  let nanoseconds
+  if (minuteString === undefined || secondString === '') {


Suggested change

if (minuteString === undefined || secondString === '') {

if (minuteString === undefined || minuteString === '') {

maybe?

robsdedude · 2026-03-10T08:48:29Z

packages/core/src/temporal-types.ts

+  let nanoseconds
+  if (minuteString === undefined || secondString === '') {
+    hours = parseTemporalInt(hourString, 'hours')
+    minutes = int(decimalString !== undefined ? Math.round(parseFloat('0' + decimalString) * 60) : 0)


How about once at the top:

decimalInt = decimalString !== undefined ? parseFloat('0' + decimalString) : 0

and then saving a whole bunch of undefined checks and string parsing calls.

robsdedude · 2026-03-10T08:55:04Z

packages/core/src/temporal-types.ts

+  let minutes
+  let seconds
+  let nanoseconds
+  if (minuteString === undefined || secondString === '') {


The way the regexs are written rn, minuteString can be undefined while secondString isn't, I believe. If so, that'd lead to secondString being ignored erroneously.

They also allow for T01::.2. They probably shouldn't, but if they do, at least the .2 should mean 0.2 seconds, not 0.2 hours.

MaxAake added 23 commits November 19, 2025 15:08

Enable Object Mapping for Parameters

7fdbc14

deno sync

8974b0e

fix tests

8bed085

Update bolt-v3.test.js

596cb31

support converting lists of params and add asInteger

cdfcbf3

deno sync

70bbadb

remove as integer, makes no sense with asNumber and asBigInt

68f84e0

drop lingering bits of asInteger

6466d4b

fix temporal bugs and some renaming

232b11a

deno sync

86254dc

document temporal types string parsing

66ead65

deno sync

a107800

add tests for string parsing temporal types

2e53950

deno sync

de76027

improve duration parsing

1040d63

deno sync

c3e03f4

error message testing

0127f10

improve test and take record object mapping out of preview

6cf1e45

Update record-object-mapping.test.js

224031e

test nested maps and dont ignore parameter mapping for optionals

9c410e9

Update record-object-mapping.test.js

1f34571

deno sync

d102b06

fix typo, allow parsing zoned datetimes

0587594

MaxAake marked this pull request as ready for review January 29, 2026 14:33

robsdedude self-requested a review January 30, 2026 10:03

robsdedude reviewed Jan 30, 2026

View reviewed changes

robsdedude requested changes Feb 2, 2026

View reviewed changes

MaxAake added 2 commits February 26, 2026 09:42

Fixing most review comments

d760fcd

deno sync

eae1683

MaxAake added 6 commits February 26, 2026 10:08

query parameterRules should only override default rules if provided

f59c279

Update deno.lock

17b760e

allow optional fields to be missing

e26d70b

deno sync

8c52440

add string parser for Date to avoid needing to export JSDate

9601d8e

deno sync

0bc3c1b

MaxAake requested a review from robsdedude March 4, 2026 08:23

Update temporal-types.test.ts

2f3ac83

robsdedude reviewed Mar 9, 2026

View reviewed changes

robsdedude reviewed Mar 10, 2026

View reviewed changes

	function parseTemporalFloat (str: string, field: string, maxLength?: number): number {
	function parseTemporalFloat (str: string, field: string): number {

	function handleTimeDecimals (hourString: string, minuteString: string, secondString: string, decimalString: string): [Integer, Integer, Integer, Integer] {
	function handleTimeDecimals (hourString?: string, minuteString?: string, secondString?: string, decimalString?: string): [Integer, Integer, Integer, Integer] {

	if (minuteString === undefined \|\| secondString === '') {
	if (minuteString === undefined \|\| minuteString === '') {

Conversation

MaxAake commented Nov 19, 2025 • edited by robsdedude Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Examples

Uh oh!

robsdedude left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MaxAake commented Feb 13, 2026

Uh oh!

robsdedude left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robsdedude Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MaxAake commented Nov 19, 2025 •

edited by robsdedude

Loading

robsdedude Mar 9, 2026 •

edited

Loading