Move the Result Transformers to their own file

Author: bigmontz

packages/core/src/driver.ts

@@ -42,8 +42,8 @@ import {
 } from './types'
 import { ServerAddress } from './internal/server-address'
 import BookmarkManager, { bookmarkManager } from './bookmark-manager'
-import EagerResult, { createEagerResultFromResult } from './result-eager'
-import Result from './result'
+import EagerResult from './result-eager'
+import resultTransformers, { ResultTransformer } from './result-transformers'
 import QueryExecutor from './internal/query-executor'
 import { newError } from './error'
 
@@ -257,8 +257,6 @@ const routing = {
 
 Object.freeze(routing)
 
-type ResultTransformer<T> = (result: Result) => Promise<T>
-
 /**
  * The query configuration
  * @interface
@@ -412,11 +410,11 @@ class Driver {
    * const transformedResult = await driver.executeQuery(
    *    "<QUERY>",
    *    <PARAMETERS>,
-   *    QueryConfig {
-   *      routing: neo4j.routing.WRITERS,
-   *      resultTransformer: transformer,
-   *      database: "<DATABASE>",
-   *      impersonatedUser: "<USER>",
+   *    {
+   *       routing: neo4j.routing.WRITERS,
+   *       resultTransformer: transformer,
+   *       database: "<DATABASE>",
+   *       impersonatedUser: "<USER>",
    *       bookmarkManager: bookmarkManager
    *    })
    * // are equivalent to those
@@ -436,14 +434,15 @@ class Driver {
    * }
    *
    * @public
+   * @experimental
    * @param {string | {text: string, parameters?: object}} 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>}
    */
   async executeQuery<T> (query: Query, parameters?: any, config: QueryConfig<T> = {}): Promise<T> {
     const bookmarkManager = config.bookmarkManager === null ? undefined : (config.bookmarkManager ?? this.queryBookmarkManager)
-    const resultTransformer = (config.resultTransformer ?? createEagerResultFromResult) as ResultTransformer<T>
+    const resultTransformer = (config.resultTransformer ?? resultTransformers.eagerResultTransformer()) as ResultTransformer<T>
     const routingConfig: string = config.routing ?? routing.WRITERS
 
     if (routingConfig !== routing.READERS && routingConfig !== routing.WRITERS) {
@@ -799,6 +798,6 @@ function createHostNameResolver (config: any): ConfiguredCustomResolver {
   return new ConfiguredCustomResolver(config.resolver)
 }
 
-export { Driver, READ, WRITE, routing, SessionConfig}
+export { Driver, READ, WRITE, routing, SessionConfig }
 export type { QueryConfig, RoutingControl }
 export default Driver

packages/core/src/index.ts

@@ -80,6 +80,7 @@ import BookmarkManager, { BookmarkManagerConfig, bookmarkManager } from './bookm
 import { SessionConfig, QueryConfig, RoutingControl, routing } from './driver'
 import * as types from './types'
 import * as json from './json'
+import resultTransformers, { ResultTransformer } from './result-transformers'
 import * as internal from './internal' // todo: removed afterwards
 
 /**
@@ -152,7 +153,8 @@ const forExport = {
   json,
   auth,
   bookmarkManager,
-  routing
+  routing,
+  resultTransformers
 }
 
 export {
@@ -214,7 +216,8 @@ export {
   json,
   auth,
   bookmarkManager,
-  routing
+  routing,
+  resultTransformers
 }
 
 export type {
@@ -228,7 +231,8 @@ export type {
   BookmarkManagerConfig,
   SessionConfig,
   QueryConfig,
-  RoutingControl
+  RoutingControl,
+  ResultTransformer
 }
 
 export default forExport

packages/core/src/result-eager.ts

@@ -19,7 +19,6 @@
 
 import Record, { Dict } from './record'
 import ResultSummary from './result-summary'
-import Result from './result'
 
 /**
  * Represents the fully streamed result
@@ -58,17 +57,3 @@ export default class EagerResult<Entries extends Dict = Dict> {
     this.summary = summary
   }
 }
-
-/**
- * Creates an {@link EagerResult} from a given {@link Result} by
- * consuming the whole stream.
- *
- * @private
- * @param {Result} result The result to be consumed
- * @returns A promise of an EagerResult
- */
-export async function createEagerResultFromResult<Entries extends Dict = Dict> (result: Result): Promise<EagerResult<Entries>> {
-  const { summary, records } = await result
-  const keys = await result.keys()
-  return new EagerResult<Entries>(keys, records, summary)
-}

packages/core/src/result-transformers.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 { Dict } from './record'
+import Result from './result'
+import EagerResult from './result-eager'
+
+async function createEagerResultFromResult<Entries extends Dict> (result: Result): Promise<EagerResult<Entries>> {
+  const { summary, records } = await result
+  const keys = await result.keys()
+  return new EagerResult<Entries>(keys, records, summary)
+}
+
+type ResultTransformer<T> = (result: Result) => Promise<T>
+/**
+ * Protocol for transforming {@link Result}.
+ *
+ * @typedef {function<T>(result:Result):Promise<T>} ResultTransformer
+ * @interface
+ * @experimental
+ *
+ * @see {@link resultTransformers} for provided implementations.
+ * @see {@link Driver#executeQuery} for usage.
+ *
+ */
+/**
+ * Defines the object which holds the common {@link ResultTransformer} used with {@link Driver#executeQuery}.
+ *
+ * @experimental
+ */
+class ResultTransformers {
+  /**
+   * Creates a {@link ResultTransformer} which transforms {@link Result} to {@link EagerResult}
+   * by consuming the whole stream.
+   *
+   * This is the default implementation used in {@link Driver#executeQuery}
+   *
+   * @example
+   * // This:
+   * const { keys, records, summary } = await driver.executeQuery('CREATE (p:Person{ name: $name }) RETURN p', { name: 'Person1'}, {
+   *   resultTransformer: neo4j.resultTransformers.eagerResultTransformer()
+   * })
+   * // equivalent to:
+   * const { keys, records, summary } = await driver.executeQuery('CREATE (p:Person{ name: $name }) RETURN p', { name: 'Person1'})
+   *
+   *
+   * @experimental
+   * @returns {ResultTransformer<EagerResult<Entries>>} The result transformer
+   */
+  eagerResultTransformer<Entries extends Dict = Dict>(): ResultTransformer<EagerResult<Entries>> {
+    return createEagerResultFromResult
+  }
+}
+
+/**
+ * Holds the common {@link ResultTransformer} used with {@link Driver#executeQuery}.
+ *
+ * @experimental
+ */
+const resultTransformers = new ResultTransformers()
+
+Object.freeze(resultTransformers)
+
+export default resultTransformers
+
+export type {
+  ResultTransformer
+}

packages/core/test/driver.test.ts

@@ -24,7 +24,7 @@ import { Logger } from '../src/internal/logger'
 import QueryExecutor from '../src/internal/query-executor'
 import { ConfiguredCustomResolver } from '../src/internal/resolver'
 import { LogLevel } from '../src/types'
-import { createEagerResultFromResult } from '../src/result-eager'
+import resultTransformers from '../src/result-transformers'
 import Record, { Dict } from '../src/record'
 
 describe('Driver', () => {
@@ -334,7 +334,7 @@ describe('Driver', () => {
 
         expect(eagerResult).toEqual(expected)
         expect(spiedExecute).toBeCalledWith({
-          resultTransformer: createEagerResultFromResult,
+          resultTransformer: resultTransformers.eagerResultTransformer(),
           bookmarkManager: driver?.queryBookmarkManager,
           routing: routing.WRITERS,
           database: undefined,
@@ -458,7 +458,7 @@ describe('Driver', () => {
       function extendsDefaultWith<T = EagerResult<Dict>> (config: QueryConfig<T>) {
         return () => {
           const defaultConfig = {
-            resultTransformer: createEagerResultFromResult,
+            resultTransformer: resultTransformers.eagerResultTransformer(),
             bookmarkManager: driver?.queryBookmarkManager,
             routing: routing.WRITERS,
             database: undefined,

packages/core/test/result-eager.test.ts

@@ -17,9 +17,7 @@
  * limitations under the License.
  */
 
-import { EagerResult, newError, Record, Result, ResultSummary } from '../src'
-import { createEagerResultFromResult } from '../src/result-eager'
-import ResultStreamObserverMock from './utils/result-stream-observer.mock'
+import { EagerResult, Record, ResultSummary } from '../src'
 
 describe('EagerResult', () => {
   it('should construct with keys, records and summary', () => {
@@ -34,81 +32,3 @@ describe('EagerResult', () => {
     expect(eagerResult.summary).toBe(summary)
   })
 })
-
-describe('createEagerResultFromResult', () => {
-  describe('with a valid result', () => {
-    it('it should return an EagerResult', async () => {
-      const resultStreamObserverMock = new ResultStreamObserverMock()
-      const query = 'Query'
-      const params = { a: 1 }
-      const meta = { db: 'adb' }
-      const result = new Result(Promise.resolve(resultStreamObserverMock), query, params)
-      const keys = ['a', 'b']
-      const rawRecord1 = [1, 2]
-      const rawRecord2 = [3, 4]
-      resultStreamObserverMock.onKeys(keys)
-      resultStreamObserverMock.onNext(rawRecord1)
-      resultStreamObserverMock.onNext(rawRecord2)
-      resultStreamObserverMock.onCompleted(meta)
-
-      const eagerResult: EagerResult = await createEagerResultFromResult(result)
-
-      expect(eagerResult.keys).toEqual(keys)
-      expect(eagerResult.records).toEqual([
-        new Record(keys, rawRecord1),
-        new Record(keys, rawRecord2)
-      ])
-      expect(eagerResult.summary).toEqual(
-        new ResultSummary(query, params, meta)
-      )
-    })
-
-    it('it should return a type-safe EagerResult', async () => {
-      interface Car {
-        model: string
-        year: number
-      }
-      const resultStreamObserverMock = new ResultStreamObserverMock()
-      const query = 'Query'
-      const params = { a: 1 }
-      const meta = { db: 'adb' }
-      const result = new Result(Promise.resolve(resultStreamObserverMock), query, params)
-      const keys = ['model', 'year']
-      const rawRecord1 = ['Beautiful Sedan', 1987]
-      const rawRecord2 = ['Hot Hatch', 1995]
-
-      resultStreamObserverMock.onKeys(keys)
-      resultStreamObserverMock.onNext(rawRecord1)
-      resultStreamObserverMock.onNext(rawRecord2)
-      resultStreamObserverMock.onCompleted(meta)
-
-      const eagerResult: EagerResult<Car> = await createEagerResultFromResult(result)
-
-      expect(eagerResult.keys).toEqual(keys)
-      expect(eagerResult.records).toEqual([
-        new Record(keys, rawRecord1),
-        new Record(keys, rawRecord2)
-      ])
-      expect(eagerResult.summary).toEqual(
-        new ResultSummary(query, params, meta)
-      )
-
-      const [car1, car2] = eagerResult.records.map(record => record.toObject())
-
-      expect(car1.model).toEqual(rawRecord1[0])
-      expect(car1.year).toEqual(rawRecord1[1])
-
-      expect(car2.model).toEqual(rawRecord2[0])
-      expect(car2.year).toEqual(rawRecord2[1])
-    })
-  })
-
-  describe('when results fail', () => {
-    it('should propagate the exception', async () => {
-      const expectedError = newError('expected error')
-      const result = new Result(Promise.reject(expectedError), 'query')
-
-      await expect(createEagerResultFromResult(result)).rejects.toThrow(expectedError)
-    })
-  })
-})