Expand Record Object Mapping to allow Parameter Mapping

packages/core/src/driver.ts

@@ -49,6 +49,7 @@ import NotificationFilter from './notification-filter'
 import HomeDatabaseCache from './internal/homedb-cache'
 import { cacheKey } from './internal/auth-util'
 import { ProtocolVersion } from './protocol-version'
+import { Rules } from './mapping.highlevel'
 
 const DEFAULT_MAX_CONNECTION_LIFETIME: number = 60 * 60 * 1000 // 1 hour
 
@@ -368,6 +369,7 @@ class QueryConfig<T = EagerResult> {
   transactionConfig?: TransactionConfig
   auth?: AuthToken
   signal?: AbortSignal
+  parameterRules?: Rules
 
   /**
    * @constructor
@@ -630,7 +632,7 @@ class Driver {
       transactionConfig: config.transactionConfig,
       auth: config.auth,
       signal: config.signal
-    }, query, parameters)
+    }, query, parameters, config.parameterRules)
   }
 
   /**

packages/core/src/graph-types.ts

@@ -18,6 +18,7 @@ import Integer from './integer'
 import { stringify } from './json'
 import { Rules, GenericConstructor, as } from './mapping.highlevel'
 
+export const JSDate = Date
 type StandardDate = Date
 /**
  * @typedef {number | Integer | bigint} NumberOrInteger
@@ -89,8 +90,6 @@ class Node<T extends NumberOrInteger = Integer, P extends Properties = Propertie
    * @param {GenericConstructor<T> | Rules} constructorOrRules Constructor for the desired type or {@link Rules} for the hydration
    * @param {Rules} [rules] {@link Rules} for the hydration
    * @returns {T}
-   *
-   * @experimental Part of the Record Object Mapping preview feature
    */
   as <T extends {} = Object>(rules: Rules): T
   as <T extends {} = Object>(genericConstructor: GenericConstructor<T>): T
@@ -224,8 +223,6 @@ class Relationship<T extends NumberOrInteger = Integer, P extends Properties = P
    * @param {GenericConstructor<T> | Rules} constructorOrRules Constructor for the desired type or {@link Rules} for the hydration
    * @param {Rules} [rules] {@link Rules} for the hydration
    * @returns {T}
-   *
-   * @experimental Part of the Record Object Mapping preview feature
    */
   as <T extends {} = Object>(rules: Rules): T
   as <T extends {} = Object>(genericConstructor: GenericConstructor<T>): T
@@ -363,8 +360,6 @@ class UnboundRelationship<T extends NumberOrInteger = Integer, P extends Propert
    * @param {GenericConstructor<T> | Rules} constructorOrRules Constructor for the desired type or {@link Rules} for the hydration
    * @param {Rules} [rules] {@link Rules} for the hydration
    * @returns {T}
-   *
-   * @experimental Part of the Record Object Mapping preview feature
    */
   as <T extends {} = Object>(rules: Rules): T
   as <T extends {} = Object>(genericConstructor: GenericConstructor<T>): T

packages/core/src/internal/query-executor.ts

@@ -21,6 +21,7 @@ import Result from '../result'
 import ManagedTransaction from '../transaction-managed'
 import { AuthToken, Query } from '../types'
 import { TELEMETRY_APIS } from './constants'
+import { Rules } from '../mapping.highlevel'
 
 type SessionFactory = (config: { database?: string, bookmarkManager?: BookmarkManager, impersonatedUser?: string, auth?: AuthToken }) => Session
 
@@ -42,7 +43,7 @@ export default class QueryExecutor {
 
   }
 
-  public async execute<T>(config: ExecutionConfig<T>, query: Query, parameters?: any): Promise<T> {
+  public async execute<T>(config: ExecutionConfig<T>, query: Query, parameters?: any, parameterRules?: Rules): Promise<T> {
     const session = this._createSession({
       database: config.database,
       bookmarkManager: config.bookmarkManager,
@@ -65,7 +66,7 @@ export default class QueryExecutor {
         : session.executeWrite.bind(session)
 
       return await executeInTransaction(async (tx: ManagedTransaction) => {
-        const result = tx.run(query, parameters)
+        const result = tx.run(query, parameters, parameterRules)
         return await config.resultTransformer(result)
       }, config.transactionConfig)
     } finally {

packages/core/src/internal/util.ts

@@ -19,6 +19,7 @@ import Integer, { isInt, int } from '../integer'
 import { NumberOrInteger } from '../graph-types'
 import { EncryptionLevel } from '../types'
 import { stringify } from '../json'
+import { Rules, validateAndcleanParameters } from '../mapping.highlevel'
 
 const ENCRYPTION_ON: EncryptionLevel = 'ENCRYPTION_ON'
 const ENCRYPTION_OFF: EncryptionLevel = 'ENCRYPTION_OFF'
@@ -62,15 +63,16 @@ function isObject (obj: any): boolean {
  * @throws TypeError when either given query or parameters are invalid.
  */
 function validateQueryAndParameters (
-  query: string | String | { text: string, parameters?: any },
+  query: string | String | { text: string, parameters?: any, parameterRules?: Rules },
   parameters?: any,
-  opt?: { skipAsserts: boolean }
+  opt?: { skipAsserts?: boolean, parameterRules?: Rules }
 ): {
     validatedQuery: string
     params: any
   } {
   let validatedQuery: string = ''
   let params = parameters ?? {}
+  let parameterRules = opt?.parameterRules
   const skipAsserts: boolean = opt?.skipAsserts ?? false
 
   if (typeof query === 'string') {
@@ -80,9 +82,11 @@ function validateQueryAndParameters (
   } else if (typeof query === 'object' && query.text != null) {
     validatedQuery = query.text
     params = query.parameters ?? {}
+    parameterRules = query.parameterRules
   }
 
   if (!skipAsserts) {
+    params = validateAndcleanParameters(params, parameterRules)
     assertCypherQuery(validatedQuery)
     assertQueryParameters(params)
   }

packages/core/src/mapping.decorators.ts

@@ -5,7 +5,6 @@ import { rule } from './mapping.rulesfactories'
  * Class Decorator Factory that enables the Neo4j Driver to map result records to this class
  *
  * @returns {Function} Class Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function mappedClass () {
   return (_: any, context: any) => {
@@ -18,7 +17,6 @@ function mappedClass () {
  *
  * @param {Rule} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function booleanProperty (config?: Rule) {
   return (_: any, context: any) => {
@@ -31,7 +29,6 @@ function booleanProperty (config?: Rule) {
  *
  * @param {Rule} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function stringProperty (config?: Rule) {
   return (_: any, context: any) => {
@@ -44,7 +41,6 @@ function stringProperty (config?: Rule) {
  *
  * @param {Rule & { acceptBigInt?: boolean }} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function numberProperty (config?: Rule & { acceptBigInt?: boolean }) {
   return (_: any, context: any) => {
@@ -57,7 +53,6 @@ function numberProperty (config?: Rule & { acceptBigInt?: boolean }) {
  *
  * @param {Rule & { acceptNumber?: boolean }} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function bigIntProperty (config?: Rule & { acceptNumber?: boolean }) {
   return (_: any, context: any) => {
@@ -70,7 +65,6 @@ function bigIntProperty (config?: Rule & { acceptNumber?: boolean }) {
  *
  * @param {Rule} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function nodeProperty (config?: Rule) {
   return (_: any, context: any) => {
@@ -83,7 +77,6 @@ function nodeProperty (config?: Rule) {
  *
  * @param {Rule} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function relationshipProperty (config?: Rule) {
   return (_: any, context: any) => {
@@ -96,7 +89,6 @@ function relationshipProperty (config?: Rule) {
  *
  * @param {Rule} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function pathProperty (config?: Rule) {
   return (_: any, context: any) => {
@@ -109,7 +101,6 @@ function pathProperty (config?: Rule) {
  *
  * @param {Rule} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function pointProperty (config?: Rule) {
   return (_: any, context: any) => {
@@ -122,7 +113,6 @@ function pointProperty (config?: Rule) {
  *
  * @param {Rule} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function durationProperty (config?: Rule & { stringify?: boolean }) {
   return (_: any, context: any) => {
@@ -135,7 +125,6 @@ function durationProperty (config?: Rule & { stringify?: boolean }) {
  *
  * @param {Rule & { apply?: Rule }} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function listProperty (config?: Rule & { apply?: Rule }) {
   return (_: any, context: any) => {
@@ -148,7 +137,6 @@ function listProperty (config?: Rule & { apply?: Rule }) {
  *
  * @param {Rule & { asTypedList?: boolean }} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function vectorProperty (config?: Rule & { asTypedList?: boolean }) {
   return (_: any, context: any) => {
@@ -162,7 +150,6 @@ function vectorProperty (config?: Rule & { asTypedList?: boolean }) {
  *
  * @param {Rule} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function optionalProperty () {
   return (_: any, context: any) => {
@@ -176,7 +163,6 @@ function optionalProperty () {
  *
  * @param {Rule} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function mapPropertyFromName (name: string) {
   return (_: any, context: any) => {
@@ -190,7 +176,6 @@ function mapPropertyFromName (name: string) {
  *
  * @param {Rule} config
  * @returns {Function} Property Decorator
- * @experimental Part of the Record Object Mapping preview feature
  */
 function convertPropertyToType (type: any) {
   return (_: any, context: any) => {

packages/core/src/mapping.highlevel.ts

@@ -29,14 +29,15 @@ export interface Rule {
   optional?: boolean
   from?: string
   convert?: (recordValue: any, field: string) => any
+  parameterConversion?: (objectValue: any) => any
   validate?: (recordValue: any, field: string) => void
 }
 
 export type Rules = Record<string, Rule>
 
 export let rulesRegistry: Record<string, Rules> = {}
 
-let nameMapping: (name: string) => string = (name) => name
+export let nameMapping: (name: string) => string = (name) => name
 
 function register <T extends {} = Object> (constructor: GenericConstructor<T>, rules: Rules): void {
   rulesRegistry[constructor.name] = rules
@@ -71,15 +72,13 @@ function getCaseTranslator (databaseConvention: string, codeConvention: string):
 export const RecordObjectMapping = Object.freeze({
   /**
  * Clears all registered type mappings from the record object mapping registry.
- * @experimental Part of the Record Object Mapping preview feature
  */
   clearMappingRegistry,
   /**
  * Creates a translation function from record key names to object property names, for use with the {@link translateIdentifiers} function
  *
  * Recognized naming conventions are "camelCase", "PascalCase", "snake_case", "kebab-case", "SCREAMING_SNAKE_CASE"
  *
- * @experimental Part of the Record Object Mapping preview feature
  * @param {string} databaseConvention The naming convention in use in database result Records
  * @param {string} codeConvention The naming convention in use in JavaScript object properties
  * @returns {function} translation function
@@ -101,7 +100,6 @@ export const RecordObjectMapping = Object.freeze({
  *  resultTransformer: neo4j.resultTransformers.hydrated(Person)
  * })
  *
- * @experimental Part of the Record Object Mapping preview feature
  * @param {GenericConstructor} constructor The constructor function of the class to set rules for
  * @param {Rules} rules The rules to set for the provided class
  */
@@ -130,7 +128,6 @@ export const RecordObjectMapping = Object.freeze({
  * //or by registering them to the mapping registry
  * RecordObjectMapping.register(Person, personRules)
  *
- * @experimental Part of the Record Object Mapping preview feature
  * @param {function} translationFunction A function translating the names of your JS object property names to record key names
  */
   translateIdentifiers
@@ -179,6 +176,49 @@ export function valueAs (value: unknown, field: string, rule?: Rule): unknown {
 
   return ((rule?.convert) != null) ? rule.convert(value, field) : value
 }
+
+export function optionalParameterConversion (value: unknown, rule?: Rule): unknown {
+  if (rule?.optional === true && value == null) {
+    return value
+  }
+  return ((rule?.parameterConversion) != null) ? rule.parameterConversion(value) : value
+}
+
+export function validateAndcleanParameters (params: Record<string, any>, suppliedRules?: Rules): Record<string, any> {
+  const cleanedParams: Record<string, any> = {}
+  // @ts-expect-error
+  const parameterRules = getRules(params.constructor, suppliedRules)
+  if (parameterRules !== undefined) {
+    for (const key in parameterRules) {
+      if (!(parameterRules?.[key]?.optional === true)) {
+        let param = params[key]
+        if (parameterRules[key]?.parameterConversion !== undefined) {
+          param = parameterRules[key].parameterConversion(params[key])
+        }
+        if (param === undefined) {
+          throw newError('Parameter object did not include required parameter.')
+        }
+        if (parameterRules[key].validate != null) {
+          parameterRules[key].validate(param, key)
+          // @ts-expect-error
+          if (parameterRules[key].apply !== undefined) {
+            for (const entryKey in param) {
+              // @ts-expect-error
+              parameterRules[key].apply.validate(param[entryKey], entryKey)
+            }
+          }
+        }
+        const mappedKey = parameterRules[key].from ?? nameMapping(key)
+
+        cleanedParams[mappedKey] = param
+      }
+    }
+    return cleanedParams
+  } else {
+    return params
+  }
+}
+
 function getRules<T extends {} = Object> (constructorOrRules: Rules | GenericConstructor<T>, rules: Rules | undefined): Rules | undefined {
   const rulesDefined = typeof constructorOrRules === 'object' ? constructorOrRules : rules
   if (rulesDefined != null) {