Introduce Result, Record and Graph types mapping

packages/core/src/graph-types.ts

@@ -16,6 +16,7 @@
  */
 import Integer from './integer'
 import { stringify } from './json'
+import { Rules, GenericConstructor, as } from './mapping.highlevel'
 
 type StandardDate = Date
 /**
@@ -82,6 +83,22 @@ class Node<T extends NumberOrInteger = Integer, P extends Properties = Propertie
     this.elementId = _valueOrGetDefault(elementId, () => identity.toString())
   }
 
+  /**
+   * Hydrates an object of a given type with the properties of the node
+   *
+   * @param {GenericConstructor<T> | Rules} constructorOrRules Contructor for the desired type or {@link Rules} for the hydration
+   * @param {Rules} [rules] {@link Rules} for the hydration
+   * @returns {T}
+   */
+  as <T extends {} = Object>(rules: Rules): T
+  as <T extends {} = Object>(genericConstructor: GenericConstructor<T>): T
+  as <T extends {} = Object>(genericConstructor: GenericConstructor<T>, rules?: Rules): T
+  as <T extends {} = Object>(constructorOrRules: GenericConstructor<T> | Rules, rules?: Rules): T {
+    return as({
+      get: (key) => this.properties[key]
+    }, constructorOrRules, rules)
+  }
+
   /**
    * @ignore
    */
@@ -199,6 +216,22 @@ class Relationship<T extends NumberOrInteger = Integer, P extends Properties = P
     this.endNodeElementId = _valueOrGetDefault(endNodeElementId, () => end.toString())
   }
 
+  /**
+   * Hydrates an object of a given type with the properties of the relationship
+   *
+   * @param {GenericConstructor<T> | Rules} constructorOrRules Contructor for the desired type or {@link Rules} for the hydration
+   * @param {Rules} [rules] {@link Rules} for the hydration
+   * @returns {T}
+   */
+  as <T extends {} = Object>(rules: Rules): T
+  as <T extends {} = Object>(genericConstructor: GenericConstructor<T>): T
+  as <T extends {} = Object>(genericConstructor: GenericConstructor<T>, rules?: Rules): T
+  as <T extends {} = Object>(constructorOrRules: GenericConstructor<T> | Rules, rules?: Rules): T {
+    return as({
+      get: (key) => this.properties[key]
+    }, constructorOrRules, rules)
+  }
+
   /**
    * @ignore
    */
@@ -320,6 +353,22 @@ class UnboundRelationship<T extends NumberOrInteger = Integer, P extends Propert
     )
   }
 
+  /**
+   * Hydrates an object of a given type with the properties of the relationship
+   *
+   * @param {GenericConstructor<T> | Rules} constructorOrRules Contructor for the desired type or {@link Rules} for the hydration
+   * @param {Rules} [rules] {@link Rules} for the hydration
+   * @returns {T}
+   */
+  as <T extends {} = Object>(rules: Rules): T
+  as <T extends {} = Object>(genericConstructor: GenericConstructor<T>): T
+  as <T extends {} = Object>(genericConstructor: GenericConstructor<T>, rules?: Rules): T
+  as <T extends {} = Object>(constructorOrRules: GenericConstructor<T> | Rules, rules?: Rules): T {
+    return as({
+      get: (key) => this.properties[key]
+    }, constructorOrRules, rules)
+  }
+
   /**
    * @ignore
    */

packages/core/src/index.ts

@@ -82,7 +82,7 @@ import NotificationFilter, {
   notificationFilterMinimumSeverityLevel,
   NotificationFilterMinimumSeverityLevel
 } from './notification-filter'
-import Result, { QueryResult, ResultObserver } from './result'
+import Result, { MappedQueryResult, QueryResult, ResultObserver } from './result'
 import EagerResult from './result-eager'
 import ConnectionProvider, { Releasable } from './connection-provider'
 import Connection from './connection'
@@ -101,6 +101,9 @@ import * as json from './json'
 import resultTransformers, { ResultTransformer } from './result-transformers'
 import ClientCertificate, { clientCertificateProviders, ClientCertificateProvider, ClientCertificateProviders, RotatingClientCertificateProvider, resolveCertificateProvider } from './client-certificate'
 import * as internal from './internal' // todo: removed afterwards
+import { StandardCase } from './mapping.nameconventions'
+import { Rule, Rules, RecordObjectMapping } from './mapping.highlevel'
+import { RulesFactories } from './mapping.rulesfactories'
 
 /**
  * Object containing string constants representing predefined {@link Neo4jError} codes.
@@ -186,7 +189,10 @@ const forExport = {
   notificationFilterDisabledClassification,
   notificationFilterMinimumSeverityLevel,
   clientCertificateProviders,
-  resolveCertificateProvider
+  resolveCertificateProvider,
+  RulesFactories,
+  RecordObjectMapping,
+  StandardCase
 }
 
 export {
@@ -263,14 +269,18 @@ export {
   notificationFilterDisabledClassification,
   notificationFilterMinimumSeverityLevel,
   clientCertificateProviders,
-  resolveCertificateProvider
+  resolveCertificateProvider,
+  RulesFactories,
+  RecordObjectMapping,
+  StandardCase
 }
 
 export type {
   StandardDate,
   NumberOrInteger,
   NotificationPosition,
   QueryResult,
+  MappedQueryResult,
   ResultObserver,
   TransactionConfig,
   BookmarkManager,
@@ -294,7 +304,9 @@ export type {
   ClientCertificate,
   ClientCertificateProvider,
   ClientCertificateProviders,
-  RotatingClientCertificateProvider
+  RotatingClientCertificateProvider,
+  Rule,
+  Rules
 }
 
 export default forExport

packages/core/src/internal/observers.ts

@@ -16,6 +16,7 @@
  */
 
 import Record from '../record'
+import { GenericResultObserver } from '../result'
 import ResultSummary from '../result-summary'
 
 interface StreamObserver {
@@ -115,7 +116,7 @@ export interface ResultStreamObserver extends StreamObserver {
    * @param {function(metadata: Object)} observer.onCompleted - Handle stream tail, the summary.
    * @param {function(error: Object)} observer.onError - Handle errors, should always be provided.
    */
-  subscribe: (observer: ResultObserver) => void
+  subscribe: (observer: GenericResultObserver<any>) => void
 }
 
 export class CompletedObserver implements ResultStreamObserver {

packages/core/src/mapping.highlevel.ts

@@ -0,0 +1,189 @@
+/**
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { newError } from './error'
+import { nameConventions, StandardCase } from './mapping.nameconventions'
+
+/**
+ * constructor function of any class
+ */
+export type GenericConstructor<T extends {}> = new (...args: any[]) => T
+
+export interface Rule {
+  optional?: boolean
+  from?: string
+  convert?: (recordValue: any, field: string) => any
+  validate?: (recordValue: any, field: string) => void
+}
+
+export type Rules = Record<string, Rule>
+
+let rulesRegistry: Record<string, Rules> = {}
+
+let nameMapping: (name: string) => string = (name) => name
+
+function register <T extends {} = Object> (constructor: GenericConstructor<T>, rules: Rules): void {
+  rulesRegistry[constructor.toString()] = rules
+}
+
+function clearMappingRegistry (): void {
+  rulesRegistry = {}
+}
+
+function translateIdentifiers (translationFunction: (name: string) => string): void {
+  nameMapping = translationFunction
+}
+
+function getCaseTranslator (databaseConvention: string | StandardCase, codeConvention: string | StandardCase): ((name: string) => string) {
+  const keys = Object.keys(nameConventions)
+  if (!keys.includes(databaseConvention)) {
+    throw newError(
+      `Naming convention ${databaseConvention} is not recognized, 
+      please provide a recognized name convention or manually provide a translation function.`
+    )
+  }
+  if (!keys.includes(codeConvention)) {
+    throw newError(
+      `Naming convention ${codeConvention} is not recognized, 
+      please provide a recognized name convention or manually provide a translation function.`
+    )
+  }
+  // @ts-expect-error
+  return (name: string) => nameConventions[databaseConvention].encode(nameConventions[codeConvention].tokenize(name))
+}
+
+export const RecordObjectMapping = Object.freeze({
+  /**
+ * Clears all registered type mappings from the record object mapping registry.
+ * @experimental
+ */
+  clearMappingRegistry,
+  /**
+ * Creates a translation frunction 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
+ * @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
+ */
+  getCaseTranslator,
+  /**
+ * Registers a set of {@link Rules} to be used by {@link hydrated} for the provided class when no other rules are specified. This registry exists in global memory, not the driver instance.
+ *
+ * @example
+ * // The following code:
+ * const summary = await driver.executeQuery('CREATE (p:Person{ name: $name }) RETURN p', { name: 'Person1'}, {
+ *  resultTransformer: neo4j.resultTransformers.hydrated(Person, personClassRules)
+ * })
+ *
+ * can instead be written:
+ * neo4j.RecordObjectMapping.register(Person, personClassRules)
+ *
+ * const summary = await driver.executeQuery('CREATE (p:Person{ name: $name }) RETURN p', { name: 'Person1'}, {
+ *  resultTransformer: neo4j.resultTransformers.hydrated(Person)
+ * })
+ *
+ * @experimental
+ * @param {GenericConstructor} constructor The constructor function of the class to set rules for
+ * @param {Rules} rules The rules to set for the provided class
+ */
+  register,
+  /**
+ * 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.
+ *
+ * The function getCaseTranslator can be used to provide a prewritten translation function between some common naming conventions.
+ *
+ * @example
+ * //if the keys on records from the database are in ALLCAPS
+ * RecordObjectMapping.translateIdentifiers((name) => name.toUpperCase())
+ *
+ * //if you utilize PacalCase in the database and camelCase in JavaScript code.
+ * RecordObjectMapping.translateIdentifiers(mapping.getCaseTranslator("PascalCase", "camelCase"))
+ *
+ * //if a type has one odd mapping you can override the translation with the rule
+ * const personRules = {
+ *  firstName: neo4j.RulesFactories.asString(),
+ *  bornAt: neo4j.RulesFactories.asNumber({ acceptBigInt: true, optional: true })
+ *  weird_name-property: neo4j.RulesFactories.asString({from: 'homeTown'})
+ * }
+ * //These rules can then be used by providing them to a hydratedResultsMapper
+ * record.as<Person>(personRules)
+ * //or by registering them to the mapping registry
+ * RecordObjectMapping.register(Person, personRules)
+ *
+ * @experimental
+ * @param {function} translationFunction A function translating the names of your JS object property names to record key names
+ */
+  translateIdentifiers
+})
+
+interface Gettable { get: <V>(key: string) => V }
+
+export function as <T extends {} = Object> (gettable: Gettable, constructorOrRules: GenericConstructor<T> | Rules, rules?: Rules): T {
+  const GenericConstructor = typeof constructorOrRules === 'function' ? constructorOrRules : Object
+  const theRules = getRules(constructorOrRules, rules)
+  const vistedKeys: string[] = []
+
+  const obj = new GenericConstructor()
+
+  for (const [key, rule] of Object.entries(theRules ?? {})) {
+    vistedKeys.push(key)
+    _apply(gettable, obj, key, rule)
+  }
+
+  for (const key of Object.getOwnPropertyNames(obj)) {
+    if (!vistedKeys.includes(key)) {
+      _apply(gettable, obj, key, theRules?.[key])
+    }
+  }
+
+  return obj as unknown as T
+}
+
+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 field = `${obj.constructor.name}#${key}`
+  const processedValue = valueAs(value, field, rule)
+  // @ts-expect-error
+  obj[key] = processedValue ?? obj[key]
+}
+
+export function valueAs (value: unknown, field: string, rule?: Rule): unknown {
+  if (rule?.optional === true && value == null) {
+    return value
+  }
+
+  if (typeof rule?.validate === 'function') {
+    rule.validate(value, field)
+  }
+
+  return ((rule?.convert) != null) ? rule.convert(value, field) : value
+}
+function getRules<T extends {} = Object> (constructorOrRules: Rules | GenericConstructor<T>, rules: Rules | undefined): Rules | undefined {
+  const rulesDefined = typeof constructorOrRules === 'object' ? constructorOrRules : rules
+  if (rulesDefined != null) {
+    return rulesDefined
+  }
+
+  return typeof constructorOrRules !== 'object' ? rulesRegistry[constructorOrRules.toString()] : undefined
+}