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
@@ -605,7 +607,7 @@ class Driver {
    * }
    *
    * @public
-   * @param {string | {text: string, parameters?: object}} query - Cypher query to execute
+   * @param {string | {text: string, parameters?: object, parameterRules?: Rules}} query - Cypher query to execute
    * @param {Object} parameters - Map with parameters to use in the query
    * @param {QueryConfig<T>} config - The query configuration
    * @returns {Promise<T>}
@@ -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

@@ -89,8 +89,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 +222,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 +359,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 ?? 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

@@ -17,7 +17,7 @@
  * limitations under the License.
  */
 
-import { newError } from './error'
+import { Neo4jError, newError } from './error'
 import { nameConventions } from './mapping.nameconventions'
 
 /**
@@ -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 defaultNameMapping: (name: string) => string = (name) => name
 
 function register <T extends {} = Object> (constructor: GenericConstructor<T>, rules: Rules): void {
   rulesRegistry[constructor.name] = rules
@@ -47,7 +48,7 @@ function clearMappingRegistry (): void {
 }
 
 function translateIdentifiers (translationFunction: (name: string) => string): void {
-  nameMapping = translationFunction
+  defaultNameMapping = translationFunction
 }
 
 function getCaseTranslator (databaseConvention: string, codeConvention: string): ((name: string) => string) {
@@ -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
  */
@@ -110,6 +108,8 @@ export const RecordObjectMapping = Object.freeze({
  * Sets a default name translation from record keys to object properties.
  * If providing a function, provide a function that maps FROM your object properties names TO record key names.
  *
+ * NOTE: The keys of objects inside a record will only be translated if using the asObject rule with it, not by default.
+ *
  * The function getCaseTranslator can be used to provide a prewritten translation function between some common naming conventions.
  *
  * @example
@@ -130,7 +130,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
@@ -160,8 +159,16 @@ export function as <T extends {} = Object> (gettable: Gettable, constructorOrRul
 }
 
 function _apply<T extends {}> (gettable: Gettable, obj: T, key: string, rule?: Rule): void {
-  const mappedkey = nameMapping(key)
-  const value = gettable.get(rule?.from ?? mappedkey)
+  const mappedkey = defaultNameMapping(key)
+  let value
+  try {
+    value = gettable.get(rule?.from ?? mappedkey)
+  } catch (e) {
+    if (rule?.optional === true && e instanceof Neo4jError && e.message.includes('This record has no field with key')) {
+      return
+    }
+    throw e
+  }
   const field = `${obj.constructor.name}#${key}`
   const processedValue = valueAs(value, field, rule)
   // @ts-expect-error
@@ -179,6 +186,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> = {}
+  const parameterRules = getRules(Object.getPrototypeOf(params).constructor, suppliedRules)
+  if (parameterRules != null) {
+    for (const key in parameterRules) {
+      let param = params[key]
+      if (param == null && parameterRules[key].optional === true) {
+        continue
+      }
+      if (parameterRules[key].parameterConversion != null) {
+        param = parameterRules[key].parameterConversion(param)
+        if (param == null) {
+          if (parameterRules[key].optional !== true) {
+            throw newError(
+              `Mapped Parameter object did not include required parameter with key ${key}, 
+              check provided parameters and parameter rules.`
+            )
+          } else {
+            continue
+          }
+        }
+      }
+      if (parameterRules[key].validate != null) {
+        parameterRules[key].validate(param, key)
+      }
+      const mappedKey = parameterRules[key].from ?? defaultNameMapping(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) {