[Spike] feat: inclusion

examples/todo-list/src/controllers/todo-list.controller.ts

@@ -92,8 +92,17 @@ export class TodoListController {
       },
     },
   })
-  async findById(@param.path.number('id') id: number): Promise<TodoList> {
-    return await this.todoListRepository.findById(id);
+  async findById(
+    @param.path.number('id') id: number,
+    @param.query.object('filter') filter?: Filter<TodoList>,
+  ): Promise<TodoList> {
+    // somehow the filter sent in the request query is undefined
+    // will dig more.
+    // hardcoded the inclusion filter in the PoC PR
+    const hardcodedFilterForPoC = {
+      include: [{relation: 'todos'}],
+    };
+    return await this.todoListRepository.findById(id, hardcodedFilterForPoC);
   }
 
   @patch('/todo-lists/{id}', {

examples/todo-list/src/controllers/todo.controller.ts

@@ -43,8 +43,12 @@ export class TodoController {
   async findTodoById(
     @param.path.number('id') id: number,
     @param.query.boolean('items') items?: boolean,
+    @param.query.object('filter') filter?: Filter<Todo>,
   ): Promise<Todo> {
-    return await this.todoRepo.findById(id);
+    const hardcodedFilterForPoC = {
+      include: [{relation: 'todoList'}],
+    };
+    return await this.todoRepo.findById(id, hardcodedFilterForPoC);
   }
 
   @get('/todos', {

examples/todo-list/src/repositories/todo-list.repository.ts

@@ -44,6 +44,10 @@ export class TodoListRepository extends DefaultCrudRepository<
       'image',
       todoListImageRepositoryGetter,
     );
+    this._inclusionHandler.registerHandler<Todo, typeof Todo.prototype.id>(
+      'todos',
+      todoRepositoryGetter,
+    );
   }
 
   public findByTitle(title: string) {

examples/todo-list/src/repositories/todo.repository.ts

@@ -33,5 +33,9 @@ export class TodoRepository extends DefaultCrudRepository<
       'todoList',
       todoListRepositoryGetter,
     );
+    this._inclusionHandler.registerHandler<
+      TodoList,
+      typeof TodoList.prototype.id
+    >('todoList', todoListRepositoryGetter);
   }
 }

packages/repository/src/query.ts

@@ -155,6 +155,8 @@ export type Order<MT = AnyObject> = {[P in keyof MT]: Direction};
  */
 export type Fields<MT = AnyObject> = {[P in keyof MT]?: boolean};
 
+// The entity type provided for the scope filter is the source model
+// while it should be the target(related) model
 /**
  * Inclusion of related items
  *

packages/repository/src/relations/belongs-to/belongs-to-accessor.ts

@@ -48,15 +48,15 @@ export function createBelongsToAccessor<
   };
 }
 
-type BelongsToResolvedDefinition = BelongsToDefinition & {keyTo: string};
+export type BelongsToResolvedDefinition = BelongsToDefinition & {keyTo: string};
 
 /**
  * Resolves given belongsTo metadata if target is specified to be a resolver.
  * Mainly used to infer what the `keyTo` property should be from the target's
  * property id metadata
  * @param relationMeta belongsTo metadata to resolve
  */
-function resolveBelongsToMetadata(relationMeta: BelongsToDefinition) {
+export function resolveBelongsToMetadata(relationMeta: BelongsToDefinition) {
   if (!isTypeResolver(relationMeta.target)) {
     const reason = 'target must be a type resolver';
     throw new InvalidRelationError(reason, relationMeta);

packages/repository/src/relations/has-many/has-many-repository.factory.ts

@@ -56,15 +56,15 @@ export function createHasManyRepositoryFactory<
   };
 }
 
-type HasManyResolvedDefinition = HasManyDefinition & {keyTo: string};
+export type HasManyResolvedDefinition = HasManyDefinition & {keyTo: string};
 
 /**
  * Resolves given hasMany metadata if target is specified to be a resolver.
  * Mainly used to infer what the `keyTo` property should be from the target's
  * belongsTo metadata
  * @param relationMeta hasMany metadata to resolve
  */
-function resolveHasManyMetadata(
+export function resolveHasManyMetadata(
   relationMeta: HasManyDefinition,
 ): HasManyResolvedDefinition {
   if (!isTypeResolver(relationMeta.target)) {
@@ -73,7 +73,7 @@ function resolveHasManyMetadata(
   }
 
   if (relationMeta.keyTo) {
-    // The explict cast is needed because of a limitation of type inference
+    // The explicit cast is needed because of a limitation of type inference
     return relationMeta as HasManyResolvedDefinition;
   }
 

packages/repository/src/repositories/inclusion.ts

@@ -0,0 +1,96 @@
+import {Entity} from '../model';
+import {Getter} from '@loopback/core';
+import {
+  Filter,
+  Where,
+  resolveHasManyMetadata,
+  resolveBelongsToMetadata,
+  RelationMetadata,
+  RelationType,
+  constrainWhere,
+} from '../';
+import {AnyObject} from '..';
+import {DefaultCrudRepository} from './legacy-juggler-bridge';
+import {inspect} from 'util';
+import {
+  HasManyDefinition,
+  BelongsToDefinition,
+  HasManyResolvedDefinition,
+  BelongsToResolvedDefinition,
+} from '../relations';
+
+type ResolvedRelationMetadata =
+  | HasManyResolvedDefinition
+  | BelongsToResolvedDefinition;
+
+// SE: the source entity
+// TE: the target entity
+// SID: the ID of source entity
+// TID: the ID of target entity
+
+export class InclusionHandler<SE extends Entity, SID> {
+  _handlers: {[relation: string]: Function} = {};
+  constructor(public sourceRepository: DefaultCrudRepository<SE, SID>) {}
+
+  registerHandler<TE extends Entity, TID>(
+    relationName: string,
+    targetRepoGetter: Getter<DefaultCrudRepository<TE, TID>>,
+  ) {
+    this._handlers[relationName] = fetchIncludedItems;
+    const self = this;
+
+    async function fetchIncludedItems(
+      fks: SID[],
+      filter?: Filter<TE>,
+    ): Promise<TE[]> {
+      const targetRepo = await targetRepoGetter();
+      const relationDef: ResolvedRelationMetadata = self.getResolvedRelationDefinition(
+        relationName,
+      );
+      filter = filter || {};
+      filter.where = self.buildConstrainedWhere<TE>(
+        fks,
+        filter.where || {},
+        relationDef,
+      );
+      console.log(`inclusion filter: ${inspect(filter)}`);
+
+      return await targetRepo.find(filter);
+    }
+  }
+
+  findHandler(relationName: string) {
+    const errMsg =
+      `The inclusion handler for relation ${relationName} is not found!` +
+      `Make sure you defined ${relationName} properly.`;
+
+    return this._handlers[relationName] || new Error(errMsg);
+  }
+
+  buildConstrainedWhere<TE extends Entity>(
+    ids: SID[],
+    whereFilter: Where<TE>,
+    relationDef: ResolvedRelationMetadata,
+  ): Where<TE> {
+    const keyPropName: string = relationDef.keyTo;
+    const where: AnyObject = {};
+    where[keyPropName] = {inq: ids};
+    return constrainWhere(whereFilter, where as Where<TE>);
+  }
+
+  getResolvedRelationDefinition(name: string): ResolvedRelationMetadata {
+    const relationMetadata: RelationMetadata = this.sourceRepository.entityClass
+      .definition.relations[name];
+
+    switch (relationMetadata.type) {
+      case RelationType.hasMany:
+        return resolveHasManyMetadata(relationMetadata as HasManyDefinition);
+      case RelationType.belongsTo:
+        return resolveBelongsToMetadata(
+          relationMetadata as BelongsToDefinition,
+        );
+      default:
+        throw new Error(`Unsupported relation type ${relationMetadata.type}`);
+    }
+  }
+}

packages/repository/src/repositories/index.ts

@@ -8,3 +8,4 @@ export * from './legacy-juggler-bridge';
 export * from './kv.repository.bridge';
 export * from './repository';
 export * from './constraint-utils';
+export * from './inclusion';

packages/repository/src/repositories/legacy-juggler-bridge.ts

@@ -31,6 +31,8 @@ import {
 } from '../relations';
 import {resolveType} from '../type-resolver';
 import {EntityCrudRepository} from './repository';
+import * as utils from 'util';
+import {InclusionHandler} from './inclusion';
 
 export namespace juggler {
   export import DataSource = legacy.DataSource;
@@ -80,6 +82,7 @@ export function ensurePromise<T>(p: legacy.PromiseOrVoid<T>): Promise<T> {
 export class DefaultCrudRepository<T extends Entity, ID>
   implements EntityCrudRepository<T, ID> {
   modelClass: juggler.PersistedModelClass;
+  _inclusionHandler: InclusionHandler<T, ID>;
 
   /**
    * Constructor of DefaultCrudRepository
@@ -103,6 +106,7 @@ export class DefaultCrudRepository<T extends Entity, ID>
     );
 
     this.setupPersistedModel(definition);
+    this._inclusionHandler = new InclusionHandler(this);
   }
 
   // Create an internal legacy Model attached to the datasource
@@ -252,13 +256,39 @@ export class DefaultCrudRepository<T extends Entity, ID>
   }
 
   async findById(id: ID, filter?: Filter<T>, options?: Options): Promise<T> {
+    // advanced discussion: cache the related items
+    const relatedItems = {} as AnyObject;
+    if (filter && filter.include) {
+      for (let i of filter.include) {
+        const results = await this._fetchIncludedItems(
+          i.relation,
+          [id],
+          i.scope,
+        );
+        if (results) relatedItems[i.relation] = results;
+      }
+      delete filter.include;
+    }
     const model = await ensurePromise(
       this.modelClass.findById(id, filter as legacy.Filter, options),
     );
     if (!model) {
       throw new EntityNotFoundError(this.entityClass, id);
     }
-    return this.toEntity(model);
+    return Object.assign(this.toEntity(model), relatedItems);
+  }
+
+  async _fetchIncludedItems(
+    relation: string,
+    ids: ID[],
+    filter?: Filter<AnyObject>,
+  ) {
+    const handler = this._inclusionHandler.findHandler(relation);
+    if (!handler) {
+      throw new Error('Fetch included items is not supported');
+    }
+    const includedItems = await handler(ids, filter);
+    return includedItems;
   }
 
   update(entity: T, options?: Options): Promise<void> {

packages/repository/test/acceptance/belongs-to.relation.acceptance.ts

@@ -39,6 +39,18 @@ describe('BelongsTo relation', () => {
     expect(result).to.deepEqual(customer);
   });
 
+  it('can find order includes customer', async () => {
+    const customer = await customerRepo.create({name: 'Order McForder'});
+    const order = await orderRepo.create({
+      customerId: customer.id,
+      description: 'Order from Order McForder, the hoarder of Mordor',
+    });
+    const result = await controller.findOrderIncludesCustomer(order.id);
+    // The code won't work since Order model doesn't have a property called customer
+    // expect(result.customer.length).to.equal(1);
+    // expect(result.customer[0]).to.deepEqual(customer);
+  });
+
   //--- HELPERS ---//
 
   class OrderController {
@@ -49,6 +61,10 @@ describe('BelongsTo relation', () => {
     async findOwnerOfOrder(orderId: string) {
       return await this.orderRepository.customer(orderId);
     }
+    async findOrderIncludesCustomer(orderId: string) {
+      const inclusionFilter = {include: [{relation: 'customer'}]};
+      return await this.orderRepository.findById(orderId, inclusionFilter);
+    }
   }
 
   function givenApplicationWithMemoryDB() {

packages/repository/test/acceptance/has-many.relation.acceptance.ts

@@ -69,6 +69,23 @@ describe('HasMany relation', () => {
     expect(persisted).to.deepEqual(foundOrders);
   });
 
+  it('can find related instances with include filter', async () => {
+    const order = await controller.createCustomerOrders(existingCustomerId, {
+      description: 'order 1',
+    });
+    const notMyOrder = await controller.createCustomerOrders(
+      existingCustomerId + 1,
+      {
+        description: 'order 2',
+      },
+    );
+    const foundCustomer = await controller.findCustomerIncludesOrders(
+      existingCustomerId,
+    );
+    expect(foundCustomer.orders.length).to.equal(1);
+    expect(foundCustomer.orders[0]).to.containEql(order);
+  });
+
   it('can patch many instances', async () => {
     await controller.createCustomerOrders(existingCustomerId, {
       description: 'order 1',
@@ -166,6 +183,14 @@ describe('HasMany relation', () => {
     async deleteCustomerOrders(customerId: number) {
       return await this.customerRepository.orders(customerId).delete();
     }
+
+    async findCustomerIncludesOrders(customerId: number) {
+      const inclusionFilter = {include: [{relation: 'orders'}]};
+      return await this.customerRepository.findById(
+        customerId,
+        inclusionFilter,
+      );
+    }
   }
 
   function givenApplicationWithMemoryDB() {

packages/repository/test/fixtures/repositories/customer.repository.ts

@@ -43,5 +43,9 @@ export class CustomerRepository extends DefaultCrudRepository<
       'address',
       addressRepositoryGetter,
     );
+    this._inclusionHandler.registerHandler<Order, typeof Order.prototype.id>(
+      'orders',
+      orderRepositoryGetter,
+    );
   }
 }

packages/repository/test/fixtures/repositories/order.repository.ts

@@ -32,5 +32,9 @@ export class OrderRepository extends DefaultCrudRepository<
       'customer',
       customerRepositoryGetter,
     );
+    this._inclusionHandler.registerHandler<
+      Customer,
+      typeof Customer.prototype.id
+    >('customer', customerRepositoryGetter);
   }
 }