implement queryAndMap()

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change Log (@egomobile/orm)
 
+## 0.7.0
+
+- add [queryAndMap()](https://egomobile.github.io/node-orm/interfaces/IDataRepository.html#queryAndMap)
+
 ## 0.6.1
 
 - add types which helpds to realize data transformations between databases and entities

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@egomobile/orm",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "A simple and generic ORM mapper.",
   "main": "lib/index.js",
   "engines": {

src/classes/DataAdapterBase.ts

@@ -145,6 +145,11 @@ export abstract class DataAdapterBase implements IDataAdapter {
      */
     public abstract query(q: any, ...paramsOrArgs: any[]): Promise<any>;
 
+    /**
+     * @inheritdoc
+     */
+    public abstract queryAndMap(type: Constructor<any>, q: any, ...paramsOrArgs: any[]): Promise<any[]>;
+
     /**
      * @inheritdoc
      */

src/classes/DataContext.ts

@@ -53,6 +53,10 @@ export class DataContext implements IDataContext {
         return this.options.adapter.query(q, ...paramsOrArgs);
     }
 
+    public queryAndMap<T extends any = any>(type: Constructor<T>, q: any, ...paramsOrArgs: any[]): Promise<T[]> {
+        return this.options.adapter.queryAndMap(type, q, ...paramsOrArgs);
+    }
+
     public remove<T extends any = any>(entities: T | List<T>) {
         return this.options.adapter.remove<T>(entities);
     }

src/types/index.ts

@@ -193,6 +193,49 @@ export interface IDataRepository {
      */
     query<T extends any = any>(q: any, ...paramsOrArgs: any[]): Promise<T>;
 
+    /**
+     * Does a raw query and maps the result(s) to entity objects.
+     * The classes do not need to be configured in context, so it is
+     * possbile to implement and work with "joins".
+     *
+     * @example
+     * ```
+     * import { IDataRepository } from '@egomobile/orm'
+     *
+     * class UserAndRole {
+     *   role_id!: string;
+     *   user_id!: string;
+     * }
+     *
+     * async function loadUserRoles(repo: IDataRepository): Promise<UserAndRole[]> {
+     *   // PostgreSQL example
+     *   // s. https://github.com/egomobile/node-orm-pg
+     *
+     *   return await repo.queryAndMap(
+     *     UserAndRole,  // type of the target entity
+     *                   // does not need to be configured
+     *                   // in data context
+     *
+     *     // build query
+     *     "SELECT DISTINCT ur.id AS role_id, u.id AS user_id " +
+     *     "FROM user_roles ur " +
+     *     "INNER JOIN users u ON u.id = ur.user_id " +
+     *     "WHERE u.is_active = $1 AND u.is_deleted = $2;",
+     *
+     *     // additional parameters
+     *     true, false  // $1, $2
+     *   )
+     * }
+     * ```
+     *
+     * @param {Constructor<T>} type The target type.
+     * @param {any} q The object / value, which represents the query.
+     * @param {any[]} [paramsOrArgs] A list of optional parameters or arguments for the query.
+     *
+     * @returns {Promise<T[]>} The promise with the mapped entities.
+     */
+    queryAndMap<T extends any = any>(type: Constructor<T>, q: any, ...paramsOrArgs: any[]): Promise<T[]>;
+
     /**
      * Removes one or more entities.
      *