feat(repository): implement inclusion resolver for hasOne relation

Co-authored-by: Miroslav <[email protected]>

docs/site/BelongsTo-relation.md

@@ -270,12 +270,8 @@ on constructor to avoid "Circular dependency" error (see
 
 ## Querying related models
 
-LoopBack 4 has the concept of an `inclusion resolver` in relations, which helps
-to query data through an `include` filter. An inclusion resolver is a function
-that can fetch target models for the given list of source model instances.
-LoopBack 4 creates a different inclusion resolver for each relation type.
-
-The following is an example for using BelongsTo inclusion resolvers:
+A `belongsTo` relation has an `inclusionResolver` function as a property. It
+fetches target models for the given list of source model instances.
 
 Use the relation between `Customer` and `Order` we show above, an `Order`
 belongs to a `Customer`.

docs/site/HasMany-relation.md

@@ -317,10 +317,8 @@ issue](https://github.com/strongloop/loopback-next/issues/1179) to follow the di
 
 ## Querying related models
 
-LoopBack 4 has the concept of an `inclusion resolver` in relations, which helps
-to query data through an `include` filter. An inclusion resolver is a function
-that can fetch target models for the given list of source model instances.
-LoopBack 4 creates a different inclusion resolver for each relation type.
+A `hasMany` relation has an `inclusionResolver` function as a property. It
+fetches target models for the given list of source model instances.
 
 Use the relation between `Customer` and `Order` we show above, a `Customer` has
 many `Order`s.

docs/site/Relations.md

@@ -31,7 +31,10 @@ introduction of [repositories](Repositories.md), we aim to simplify the approach
 to relations by creating constrained repositories. This means that certain
 constraints need to be honoured by the target model repository based on the
 relation definition, and thus we produce a constrained version of it as a
-navigational property on the source repository.
+navigational property on the source repository. Additionally, we also introduce
+the concept of the `inclusion resolver` in relations, which helps to query data
+over different relations. LoopBack 4 creates a different inclusion resolver for
+each relation type.
 
 Here are the currently supported relations:
 

docs/site/hasOne-relation.md

@@ -295,3 +295,87 @@ certain properties from the JSON/OpenAPI spec schema built for the `requestBody`
 payload. See its [GitHub
 issue](https://github.com/strongloop/loopback-next/issues/1179) to follow the discussion.
 " %}
+
+## Querying related models
+
+A `hasOne` relation has an `inclusionResolver` function as a property. It
+fetches target models for the given list of source model instances.
+
+Using the relation between `Supplier` and `Account` we have shown above, a
+`Supplier` has one `Account`.
+
+After setting up the relation in the repository class, the inclusion resolver
+allows users to retrieve all suppliers along with their related account
+instances through the following code:
+
+```ts
+supplierRepository.find({include: [{relation: 'account'}]});
+```
+
+### Enable/disable the inclusion resolvers:
+
+- Base repository classes have a public property `inclusionResolvers`, which
+  maintains a map containing inclusion resolvers for each relation.
+- The `inclusionResolver` of a certain relation is built when the source
+  repository class calls the `createHasOneRepositoryFactoryFor` function in the
+  constructor with the relation name.
+- Call `registerInclusionResolver` to add the resolver of that relation to the
+  `inclusionResolvers` map. (As we realized in LB3, not all relations are
+  allowed to be traversed. Users can decide to which resolvers can be added.)
+
+The following code snippet shows how to register the inclusion resolver for the
+hasOne relation 'account':
+
+```ts
+export class SupplierRepository extends DefaultCrudRepository {
+  account: HasOneRepositoryFactory<Account, typeof Supplier.prototype.id>;
+  constructor(
+    dataSource: juggler.DataSource,
+    accountRepositoryGetter: Getter<AccountRepository>,
+  ) {
+    super(Supplier, dataSource);
+    // we already have this line to create a HasOneRepository factory
+    this.account = this.createHasOneRepositoryFactoryFor(
+      'account',
+      accountRepositoryGetter,
+    );
+    // add this line to register inclusion resolver
+    this.registerInclusion('account', this.account.inclusionResolver);
+  }
+}
+```
+
+- We can simply include the relation in queries via `find()`, `findOne()`, and
+  `findById()` methods. Example:
+
+  ```ts
+  supplierRepository.find({include: [{relation: 'account'}]});
+  ```
+
+  which returns:
+
+  ```ts
+  [
+    {
+      id: 1,
+      name: 'Thor',
+      account: {accountManager: 'Odin', supplierId: 1},
+    },
+    {
+      id: 5,
+      name: 'Loki',
+      account: {accountManager: 'Frigga', supplierId: 5},
+    },
+  ];
+  ```
+
+- You can delete a relation from `inclusionResolvers` to disable the inclusion
+  for a certain relation. e.g
+  `supplierRepository.inclusionResolvers.delete('account')`
+
+{% include note.html content="
+Inclusion with custom scope:
+Besides specifying the relation name to include, it's also possible to specify additional scope constraints.
+However, this feature is not supported yet. Check our GitHub issue for more information:
+[Include related models with a custom scope](https://github.com/strongloop/loopback-next/issues/3453).
+" %}

packages/repository-tests/src/crud/relations/acceptance/belongs-to.relation.acceptance.ts

@@ -103,8 +103,6 @@ export function belongsToRelationAcceptance(
       });
       await customerRepo.deleteAll();
 
-      await orderRepo.deleteAll();
-
       await expect(findCustomerOfOrder(order.id)).to.be.rejectedWith(
         EntityNotFoundError,
       );

packages/repository-tests/src/crud/relations/acceptance/has-one.inclusion-resolver.acceptance.ts

@@ -0,0 +1,201 @@
+// Copyright IBM Corp. 2019. All Rights Reserved.
+// Node module: @loopback/repository-tests
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {expect, skipIf, toJSON} from '@loopback/testlab';
+import {Suite} from 'mocha';
+import {
+  CrudFeatures,
+  CrudRepositoryCtor,
+  CrudTestContext,
+  DataSourceOptions,
+} from '../../..';
+import {
+  deleteAllModelsInDefaultDataSource,
+  withCrudCtx,
+} from '../../../helpers.repository-tests';
+import {
+  Address,
+  AddressRepository,
+  Customer,
+  CustomerRepository,
+} from '../fixtures/models';
+import {givenBoundCrudRepositories} from '../helpers';
+
+export function hasOneInclusionResolverAcceptance(
+  dataSourceOptions: DataSourceOptions,
+  repositoryClass: CrudRepositoryCtor,
+  features: CrudFeatures,
+) {
+  skipIf<[(this: Suite) => void], void>(
+    !features.supportsInclusionResolvers,
+    describe,
+    'HasOne inclusion resolvers - acceptance',
+    suite,
+  );
+  function suite() {
+    before(deleteAllModelsInDefaultDataSource);
+    let customerRepo: CustomerRepository;
+    let addressRepo: AddressRepository;
+
+    before(
+      withCrudCtx(async function setupRepository(ctx: CrudTestContext) {
+        // this helper should create the inclusion resolvers and also
+        // register inclusion resolvers for us
+        ({customerRepo, addressRepo} = givenBoundCrudRepositories(
+          ctx.dataSource,
+          repositoryClass,
+          features,
+        ));
+        expect(customerRepo.address.inclusionResolver).to.be.Function();
+
+        await ctx.dataSource.automigrate([Customer.name, Address.name]);
+      }),
+    );
+
+    beforeEach(async () => {
+      await customerRepo.deleteAll();
+      await addressRepo.deleteAll();
+    });
+
+    it('throws an error if it tries to query nonexistent relation names', async () => {
+      const customer = await customerRepo.create({name: 'customer'});
+      await addressRepo.create({
+        street: 'home of Thor Rd.',
+        city: 'Thrudheim',
+        province: 'Asgard',
+        zipcode: '8200',
+        customerId: customer.id,
+      });
+      await expect(
+        customerRepo.find({include: [{relation: 'home'}]}),
+      ).to.be.rejectedWith(
+        `Invalid "filter.include" entries: {"relation":"home"}`,
+      );
+    });
+
+    it('returns single model instance including single related instance', async () => {
+      const thor = await customerRepo.create({name: 'Thor'});
+      const thorAddress = await addressRepo.create({
+        street: 'home of Thor Rd.',
+        city: 'Thrudheim',
+        province: 'Asgard',
+        zipcode: '8200',
+        customerId: thor.id,
+      });
+      const result = await customerRepo.find({
+        include: [{relation: 'address'}],
+      });
+
+      const expected = {
+        ...thor,
+        parentId: features.emptyValue,
+        address: thorAddress,
+      };
+      expect(toJSON(result)).to.deepEqual([toJSON(expected)]);
+    });
+
+    it('returns multiple model instances including related instances', async () => {
+      const thor = await customerRepo.create({name: 'Thor'});
+      const odin = await customerRepo.create({name: 'Odin'});
+      const thorAddress = await addressRepo.create({
+        street: 'home of Thor Rd.',
+        city: 'Thrudheim',
+        province: 'Asgard',
+        zipcode: '999',
+        customerId: thor.id,
+      });
+      const odinAddress = await addressRepo.create({
+        street: 'home of Odin Rd.',
+        city: 'Valhalla',
+        province: 'Asgard',
+        zipcode: '000',
+        customerId: odin.id,
+      });
+
+      const result = await customerRepo.find({
+        include: [{relation: 'address'}],
+      });
+
+      const expected = [
+        {
+          ...thor,
+          parentId: features.emptyValue,
+          address: thorAddress,
+        },
+        {
+          ...odin,
+          parentId: features.emptyValue,
+          address: odinAddress,
+        },
+      ];
+      expect(toJSON(result)).to.deepEqual(toJSON(expected));
+    });
+
+    it('returns a specified instance including its related model instance', async () => {
+      const thor = await customerRepo.create({name: 'Thor'});
+      const odin = await customerRepo.create({name: 'Odin'});
+      await addressRepo.create({
+        street: 'home of Thor Rd.',
+        city: 'Thrudheim',
+        province: 'Asgard',
+        zipcode: '999',
+        customerId: thor.id,
+      });
+      const odinAddress = await addressRepo.create({
+        street: 'home of Odin Rd.',
+        city: 'Valhalla',
+        province: 'Asgard',
+        zipcode: '000',
+        customerId: odin.id,
+      });
+
+      const result = await customerRepo.findById(odin.id, {
+        include: [{relation: 'address'}],
+      });
+      const expected = {
+        ...odin,
+        parentId: features.emptyValue,
+        address: odinAddress,
+      };
+      expect(toJSON(result)).to.deepEqual(toJSON(expected));
+    });
+
+    // scope field for inclusion is not supported yet
+    it('throws error if the inclusion query contains a non-empty scope', async () => {
+      const customer = await customerRepo.create({name: 'customer'});
+      await addressRepo.create({
+        street: 'home of Thor Rd.',
+        city: 'Thrudheim',
+        province: 'Asgard',
+        zipcode: '8200',
+        customerId: customer.id,
+      });
+      await expect(
+        customerRepo.find({
+          include: [{relation: 'address', scope: {limit: 1}}],
+        }),
+      ).to.be.rejectedWith(`scope is not supported`);
+    });
+
+    it('throws error if the target repository does not have the registered resolver', async () => {
+      const customer = await customerRepo.create({name: 'customer'});
+      await addressRepo.create({
+        street: 'home of Thor Rd.',
+        city: 'Thrudheim',
+        province: 'Asgard',
+        zipcode: '8200',
+        customerId: customer.id,
+      });
+      // unregister the resolver
+      customerRepo.inclusionResolvers.delete('address');
+
+      await expect(
+        customerRepo.find({include: [{relation: 'address'}]}),
+      ).to.be.rejectedWith(
+        `Invalid "filter.include" entries: {"relation":"address"}`,
+      );
+    });
+  }
+}

packages/repository-tests/src/crud/relations/helpers.ts

@@ -54,6 +54,10 @@ export function givenBoundCrudRepositories(
     'customers',
     customerRepo.customers.inclusionResolver,
   );
+  customerRepo.inclusionResolvers.set(
+    'address',
+    customerRepo.address.inclusionResolver,
+  );
 
   const orderRepoClass = createOrderRepo(repositoryClass);
   const orderRepo: OrderRepository = new orderRepoClass(