@loopback/docs 4.0.2 → 5.0.0

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.0.0](https://github.com/loopbackio/loopback-next/compare/@loopback/docs@4.0.4...@loopback/docs@5.0.0) (2022-05-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* remove node v12 support
+
+### Features
+
+* add polymorphic relations ([f4b8158](https://github.com/loopbackio/loopback-next/commit/f4b8158387222ec64fe7ef6971da8151f2016dda)), closes [#2487](https://github.com/loopbackio/loopback-next/issues/2487)
+* add support for node v18 ([ccb4c61](https://github.com/loopbackio/loopback-next/commit/ccb4c61307d94ab7bb07a19c547dfc4fa7d388a8))
+* remove node v12 support ([5f66e5b](https://github.com/loopbackio/loopback-next/commit/5f66e5bd288ba806b3aa6550fc29c5009de8b60d))
+* **repository:** support `ReferencesMany` relation ([371a6dc](https://github.com/loopbackio/loopback-next/commit/371a6dcdf32d1a9a674f22528160b775f6639364))
+
+
+
+## [4.0.4](https://github.com/loopbackio/loopback-next/compare/@loopback/docs@4.0.3...@loopback/docs@4.0.4) (2022-03-29)
+
+
+### Bug Fixes
+
+* **docs:** update 'Migrating datasources' dead link ([1a314c9](https://github.com/loopbackio/loopback-next/commit/1a314c92ee82a9698739549007f24995047749f9))
+
+
+
+
+
+## [4.0.3](https://github.com/loopbackio/loopback-next/compare/@loopback/docs@4.0.2...@loopback/docs@4.0.3) (2022-02-28)
+
+**Note:** Version bump only for package @loopback/docs
+
+
+
+
+
 ## [4.0.2](https://github.com/loopbackio/loopback-next/compare/@loopback/docs@4.0.1...@loopback/docs@4.0.2) (2022-02-14)
 
 

package/CODE_OF_CONDUCT.md

@@ -1,4 +1,54 @@
-# Contributor Covenant Code of Conduct
+# Code of Conduct
+
+LoopBack, as member project of the OpenJS Foundation, use
+[Contributor Covenant v2.0](https://contributor-covenant.org/version/2/0/code_of_conduct)
+as their code of conduct. The full text is included
+[below](#contributor-covenant-code-of-conduct-v2.0) in English, and translations
+are available from the Contributor Covenant organisation:
+
+- [contributor-covenant.org/translations](https://www.contributor-covenant.org/translations)
+- [github.com/ContributorCovenant](https://github.com/ContributorCovenant/contributor_covenant/tree/release/content/version/2/0)
+
+Refer to the sections on reporting and escalation in this document for the
+specific emails that can be used to report and escalate issues.
+
+## Reporting
+
+### Project Spaces
+
+For reporting issues in spaces related to LoopBack, please use the email
+`tsc@loopback.io`. The LoopBack Technical Steering Committee (TSC) handles CoC
+issues related to the spaces that it maintains. The project TSC commits to:
+
+- maintain the confidentiality with regard to the reporter of an incident
+- to participate in the path for escalation as outlined in the section on
+  Escalation when required.
+
+### Foundation Spaces
+
+For reporting issues in spaces managed by the OpenJS Foundation, for example,
+repositories within the OpenJS organization, use the email
+`report@lists.openjsf.org`. The Cross Project Council (CPC) is responsible for
+managing these reports and commits to:
+
+- maintain the confidentiality with regard to the reporter of an incident
+- to participate in the path for escalation as outlined in the section on
+  Escalation when required.
+
+## Escalation
+
+The OpenJS Foundation maintains a Code of Conduct Panel (CoCP). This is a
+foundation-wide team established to manage escalation when a reporter believes
+that a report to a member project or the CPC has not been properly handled. In
+order to escalate to the CoCP send an email to
+`coc-escalation@lists.openjsf.org`.
+
+For more information, refer to the full
+[Code of Conduct governance document](https://github.com/openjs-foundation/cross-project-council/blob/HEAD/CODE_OF_CONDUCT.md).
+
+---
+
+## Contributor Covenant Code of Conduct v2.0
 
 ## Our Pledge
 
@@ -60,8 +110,8 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-[reachsl@us.ibm.com](mailto:reachsl@us.ibm.com). All complaints will be reviewed
-and investigated promptly and fairly.
+[tsc@loopback.io](mailto:tsc@loopback.io). All complaints will be reviewed and
+investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the
 reporter of any incident.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loopback/docs",
   "description": "Documentation files rendered at [https://loopback.io](https://loopback.io)",
-  "version": "4.0.2",
+  "version": "5.0.0",
   "keywords": [
     "LoopBack",
     "docs"
@@ -16,7 +16,7 @@
     "directory": "docs"
   },
   "engines": {
-    "node": "12 || 14 || 16 || 17"
+    "node": "14 || 16 || 17 || 18"
   },
   "scripts": {
     "version": "node ./bin/copy-readmes.js && node ./bin/copy-changelogs.js && cd .. && npm run tsdocs",
@@ -32,11 +32,11 @@
     "site/"
   ],
   "dependencies": {
-    "fs-extra": "^10.0.0",
-    "tslib": "^2.3.1"
+    "fs-extra": "^10.1.0",
+    "tslib": "^2.4.0"
   },
   "devDependencies": {
-    "@loopback/build": "^8.1.0"
+    "@loopback/build": "^9.0.0"
   },
-  "gitHead": "e16818ccb01edc0269ef6c45b022c5f1b67f852c"
+  "gitHead": "61453a3d7a16f9f37875a3f2c2a071568eb3e3af"
 }

package/site/CHANGELOG.md

@@ -74,6 +74,7 @@ permalink: /doc/en/lb4/changelog.index.html
 - [@loopback/example-metrics-prometheus](changelogs/examples/metrics-prometheus/CHANGELOG.md)
 - [@loopback/example-multi-tenancy](changelogs/examples/multi-tenancy/CHANGELOG.md)
 - [@loopback/example-passport-login](changelogs/examples/passport-login/CHANGELOG.md)
+- [@loopback/example-references-many](changelogs/examples/references-many/CHANGELOG.md)
 - [@loopback/example-rest-crud](changelogs/examples/rest-crud/CHANGELOG.md)
 - [@loopback/example-rpc-server](changelogs/examples/rpc-server/CHANGELOG.md)
 - [@loopback/example-soap-calculator](changelogs/examples/soap-calculator/CHANGELOG.md)

package/site/MONOREPO.md

@@ -40,6 +40,7 @@ one in the monorepo: `npm run update-monorepo-file`
 | [examples/todo-jwt](https://github.com/loopbackio/loopback-next/tree/master/examples/todo-jwt)                                       | @loopback/example-todo-jwt                 | A modified Todo tutorial how to build an application with JWT authentication and LoopBack 4                                                                                                                                                                                                     |
 | [examples/todo-list](https://github.com/loopbackio/loopback-next/tree/master/examples/todo-list)                                     | @loopback/example-todo-list                | Continuation of the todo example using relations in LoopBack 4.                                                                                                                                                                                                                                 |
 | [examples/validation-app](https://github.com/loopbackio/loopback-next/tree/master/examples/validation-app)                           | @loopback/example-validation-app           | An example demonstrating how to add validation in a LoopBack 4 application                                                                                                                                                                                                                      |
+| [examples/references-many](https://github.com/loopbackio/loopback-next/tree/master/examples/references-many)                         | @loopback/example-references-many          | An example of references many relation in a LoopBack 4                                                                                                                                                                                                                                          |
 | [examples/webpack](https://github.com/loopbackio/loopback-next/tree/master/examples/webpack)                                         | @loopback/example-webpack                  | An example to bundle @loopback/core using webpack                                                                                                                                                                                                                                               |
 | [extensions/apiconnect](https://github.com/loopbackio/loopback-next/tree/master/extensions/apiconnect)                               | @loopback/apiconnect                       | An extension for IBM API Connect                                                                                                                                                                                                                                                                |
 | [extensions/authentication-jwt](https://github.com/loopbackio/loopback-next/tree/master/extensions/authentication-jwt)               | @loopback/authentication-jwt               | Extension for the prototype of JWT authentication                                                                                                                                                                                                                                               |

package/site/Polymorphic-relations.md

@@ -0,0 +1,123 @@
+---
+lang: en
+title: 'Polymorphic Relations'
+keywords: LoopBack 4.0, LoopBack 4, Node.js, TypeScript, OpenAPI, Model Relation
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Polymorphic-relation.html
+---
+
+## Overview
+
+LoopBack supports _polymorphic relations_ in which a model can belong to more
+than one other model, on a single association.
+
+The examples below use the following example models: `Delivery`, `Letter`,
+`Parcel`, where a `Delivery` may contain a `Deliverable` - either a `Letter` or
+a `Parcel`.
+
+## Model definition
+
+We first define `Deliverable`s:
+
+```javascript
+class Deliverable extends Entity {
+}
+
+class Letter extends Deliverable {
+}
+
+class Parcel extends Deliverable {
+}
+...
+```
+
+The relation between the `Delivery` and `Deliverable`s is: `Delivery` `hasOne`
+`Deliverable`; the relation is polymorphic.
+
+```javascript
+class Delivery extends Entity {
+@hasOne(() => Deliverable, {polymorphic: true})
+  deliverable: Deliverable;
+
+deliverableType: string;
+}
+...
+```
+
+A customized discriminator can be specified. The discriminator parameter
+specifies the name of a field in the model indicating the actual type of the
+`Deliverable`.
+
+```javascript
+class Delivery extends Entity {
+@hasOne(() => Deliverable, {polymorphic: {discriminator: "deliverable_type"}})
+  deliverable: Deliverable;
+
+deliverable_type: string;
+}
+...
+```
+
+## Setting up repository
+
+The only difference on the repository class is that instead of having a single
+repository getter, a dictionary of subclass repository getters is passed into
+the repository factory creater.
+
+```javascript
+export class DeliveryRepository extends DefaultCrudRepository {
+  public readonly deliverable: HasOneRepositoryFactory<Deliverable, typeof Delivery.prototype.id>;
+
+  constructor(
+    dataSource: juggler.DataSource,
+    @repository.getter('LetterRepository')
+    protected letterRepositoryGetter: Getter<EntityCrudRepository<Deliverable, typeof Deliverable.prototype.id, DeliverableRelations>>,
+    @repository.getter('ParcelRepository')
+    protected parcelRepositoryGetter: Getter<EntityCrudRepository<Deliverable, typeof Deliverable.prototype.id, DeliverableRelations>>,
+  ) {
+    super(Delivery, dataSource);
+    this.deliverable = this.createHasOneRepositoryFactoryFor(
+      'deliverable',
+      // use a dictionary of repoGetters instead of a single repoGetter instance
+      {Letter: letterRepositoryGetter, Parcel: parcelRepositoryGetter},
+    );
+    this.registerInclusionResolver('deliverable', this.deliverable.inclusionResolver);
+  }
+}
+...
+```
+
+## Operations
+
+The polymorphic relation supports queries with inclusions
+
+```javascript
+const result = await deliveryRepo.findById(delivery1.id, {
+  include: ['deliverable'],
+});
+...
+```
+
+The instances of polymorphic relations can be created through repository
+operations
+
+```javascript
+deliveryRepo
+.deliverable(deliveryId)
+.create(letter1Data, {polymorphicType: "Letter"});
+...
+```
+
+## belongsTo, hasMany, hasManyThrough relations
+
+Polymorphic relation on `belongsTo` is similar to `hasOne`.
+
+Polymorphic relation is not supported on `hasMany` relations. However, there is
+an easy workaround: having a `hasMany` relation on a non-polymorphic concrete
+type which `hasOne` polymorphic relation with an abstract polymorphic type. For
+example, `Delivery` `hasMany` `DeliveryDeliverablePair` and
+`DeliveryDeliverablePair` `hasOne` `Deliverable`.
+
+The polymorphic relation on `hasManyThrough` relation is on the target model,
+not the through model. The discriminator is defined on the through model, and
+the target model is polymorphic.

package/site/ReferencesMany-relation.md

@@ -0,0 +1,379 @@
+---
+lang: en
+title: 'referencesMany Relation'
+keywords: LoopBack 4.0, LoopBack 4, Node.js, TypeScript, OpenAPI, Model Relation
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/ReferencesMany-relation.html
+---
+
+## Overview
+
+{% include important.html content="Please read [Relations](Relations.md) first." %}
+
+LoopBack relations enable you to create connections between models and provide
+navigation APIs to deal with a graph of model instances. In addition to the
+traditional ones, LoopBack supports `referencesMany` relation that embeds an
+array of foreign keys to reference other objects. For example:
+
+```json
+{
+  "id": 1,
+  "name": "John Smith",
+  "accountIds": ["saving-01", "checking-01"]
+}
+```
+
+To add a `referencesMany` relation to your LoopBack application, you need to
+perform the following steps:
+
+1. Add a property to your source model to define the array of foreign keys.
+2. Modify the source model repository class to provide an accessor function for
+   obtaining the target model instances.
+3. Call the accessor function in your controller methods.
+
+## Defining a referencesMany relation
+
+This section describes how to define a `referencesMany` relation at the model
+level using the `@referencesMany` decorator to define the array of foreign keys.
+
+LB4 also provides an CLI tool `lb4 relation` to generate `referencesMany`
+relation for you. Before you check out the
+[`Relation Generator`](https://loopback.io/doc/en/lb4/Relation-generator.html)
+page, read on to learn how you can define relations to meet your requirements.
+
+### Relation Metadata
+
+LB4 uses three `keyFrom`, `keyTo` and `name` fields in the `referencesMany`
+relation metadata to configure relations. The relation metadata has its own
+default values for these three fields:
+
+<table>
+  <thead>
+    <tr>
+      <th width="95">Field Name</th>
+      <th width="260">Description</th>
+      <th width="260">Default Value</th>
+      <th>Example</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>keyFrom</code></td>
+      <td>the array property of foreign keys</td>
+      <td>the target model name appended with `Ids` in camel case</td>
+      <td><code>Customer.accountIds</code></td>
+    </tr>
+    <tr>
+      <td><code>keyTo</code></td>
+      <td>the source key of the target model</td>
+      <td>the primary key in the target model</td>
+      <td><code>Account.id</code></td>
+    </tr>
+    <tr>
+      <td><code>name</code></td>
+      <td>the name of the relation</td>
+      <td>the plural name of target model</td>
+      <td><code>accounts</code></td>
+    </tr>
+
+  </tbody>
+</table>
+
+We recommend to use default values. If you'd like to customize the name of
+foreign keys or the relation name, you'll need to specify some fields through
+the relation decorator.
+
+The standard naming convention for the property of foreign keys in the source
+model is `target name` + `Ids` (for example, Customer.accountIds).
+
+{% include code-caption.html content="/src/models/customer.model.ts" %}
+
+```ts
+import {referencesMany, Entity, model, property} from '@loopback/repository';
+import {Account} from './account.model';
+
+@model()
+export class Customer extends Entity {
+  @property({
+    type: 'number',
+    id: true,
+  })
+  id: number;
+
+  @property({
+    type: 'string',
+  })
+  name: string;
+
+  @referencesMany(() => Account)
+  accountIds: number[]; // relation name will default to `accounts`
+
+  constructor(data: Partial<Customer>) {
+    super(data);
+  }
+}
+
+export interface CustomerRelations {
+  // describe navigational properties here
+}
+
+export type CustomerWithRelations = Customer & CustomerRelations;
+```
+
+If the property name of foreign keys in the source model has to be customized
+(`account_ids` instead of `accountIds` for example), the relation name has to be
+explicitly specified in the `name` attribute of the relation definition.
+Otherwise the _default relation name_ generates by LB4 (`account_ids` in this
+case) will be the same as the customized name of foreign keys, which is invalid.
+
+{% include warning.html content="Make sure that you have different names for the property name of foreign keys and the relation name in ReferencesMany relations."%}
+
+```ts
+// import statements
+@model()
+export class Customer extends Entity {
+  @property({
+    type: 'number',
+    id: true,
+  })
+  id: number;
+
+  @property({
+    type: 'string',
+  })
+  name: string;
+
+  @referencesMany(
+    () => Account,
+    {name: 'accounts'}, // specify the relation name if fk is customized
+  )
+  account_ids: number[]; // customized foreign keys
+
+  // other properties, constructor, etc.
+}
+```
+
+If you need to use _different names for models and database columns_, to use
+`account_ids` as db column name other than `accountIds` for example, passing the
+column name in the third argument to the `referencesMany` decorator would allow
+you to do so:
+
+```ts
+class Customer extends Entity {
+  // constructor, properties, etc.
+  @referencesMany(() => Account, {keyFrom: 'accountIds'}, {name: 'account_ids'})
+  accountIds: number[];
+}
+```
+
+If you need to use another attribute other than the id property to be the source
+key of the target model (joining two tables on non-primary attribute), the
+`keyTo` attribute in the relation definition has to be stated explicitly.
+
+```ts
+class Customer extends Entity {
+  // constructor, properties, etc.
+  @referencesMany(() => Account, {keyTo: 'customized_target_property'})
+  accountIds: number[];
+}
+
+export interface CustomerRelations {
+  accounts?: AccountWithRelations[];
+}
+```
+
+{% include important.html content="LB4 doesn't support composite keys for now. e.g joining two tables with more than one source key. Related GitHub issue: [Composite primary/foreign keys](https://github.com/loopbackio/loopback-next/issues/1830)" %}
+
+## Configuring a referencesMany relation
+
+The configuration and resolution of a `referencesMany` relation takes place at
+the repository level. Once `referencesMany` relation is defined on the source
+model, then there are a couple of steps involved to configure it and use it. On
+the source repository, the following are required:
+
+- In the constructor of your source repository class, use
+  [Dependency Injection](Dependency-injection.md) to receive a getter function
+  for obtaining an instance of the target repository.
+- Declare a property with the factory function type
+  `ReferencesManyAccessor<targetModel, typeof sourceModel.prototype.id>` on the
+  source repository class.
+- call the `createReferencesManyAccessorFor` function in the constructor of the
+  source repository class with the relation name (decorated relation property on
+  the source model) and target repository instance and assign it the property
+  mentioned above.
+
+The following code snippet shows how it would look like:
+
+{% include code-caption.html
+content="/src/repositories/customer.repository.ts" %}
+
+```ts
+import {Getter, inject} from '@loopback/core';
+import {
+  ReferencesManyAccessor,
+  DefaultCrudRepository,
+  juggler,
+  repository,
+} from '@loopback/repository';
+import {Account, Customer, CustomerRelations} from '../models';
+import {AccountRepository} from '../repositories';
+
+export class CustomerRepository extends DefaultCrudRepository<
+  Customer,
+  typeof Customer.prototype.id,
+  CustomerRelations
+> {
+  public readonly accounts: ReferencesManyAccessor<
+    Account,
+    typeof Customer.prototype.id
+  >;
+
+  constructor(
+    @inject('datasources.db') protected db: juggler.DataSource,
+    @repository.getter('AccountRepository')
+    accountRepositoryGetter: Getter<AccountRepository>,
+  ) {
+    super(Customer, db);
+    this.accounts = this.createReferencesManyAccessorFor(
+      'accounts',
+      accountRepositoryGetter,
+    );
+  }
+}
+```
+
+`ReferencesManyAccessor` is a function accepting the primary key (id) of a
+source model instance (e.g. `customer.id`) and returning back the related target
+model instances (e.g. a `Account[]`). See also
+[API Docs](https://loopback.io/doc/en/lb4/apidocs.repository.belongstoaccessor.html)
+
+{% include note.html content="Notice that `CustomerRepository.create()` expects an `Customer` model only, navigational properties are not expected to be included in the target data. For instance, the following request will be rejected:
+`customerRepository.create({`
+`  id: 1,`
+`  name: 'John'`
+`  accountIds: [1]`
+`  accounts:[{id: 1, balance: 0}] // rejected`
+`})`" %}
+
+## Querying related models
+
+Different from LB3, LB4 creates a different inclusion resolver for each relation
+type to query related models. Each **relation** has its own inclusion resolver
+`inclusionResolver`. And each **repository** has a built-in property
+`inclusionResolvers` as a registry for its inclusionResolvers.
+
+A `referencesMany` 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 `Account` we show above.
+
+After setting up the relation in the repository class, the inclusion resolver
+allows users to retrieve all customers along with their related accounts through
+the following code at the repository level:
+
+```ts
+customerRepo.find({include: ['accounts']});
+```
+
+or use APIs with controllers:
+
+```
+GET http://localhost:3000/customers?filter[include][]=accounts
+```
+
+### 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 `createReferencesManyAccessorFor` 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 first parameter is the name of the relation.
+
+The following code snippet shows how to register the inclusion resolver for the
+referencesMany relation 'accounts':
+
+```ts
+export class CustomerRepository extends DefaultCrudRepository {
+  accounts: ReferencesManyAccessor<Account, typeof Customer.prototype.id>;
+
+  constructor(
+    dataSource: juggler.DataSource,
+    accountRepositoryGetter: Getter<AccountRepository>,
+  ) {
+    super(Customer, dataSource);
+
+    // we already have this line to create a ReferencesManyRepository factory
+    this.accounts = this.createReferencesManyAccessorFor(
+      'accounts',
+      accountRepositoryGetter,
+    );
+
+    // add this line to register inclusion resolver.
+    this.registerInclusionResolver('accounts', this.accounts.inclusionResolver);
+  }
+}
+```
+
+- We can simply include the relation in queries via `find()`, `findOne()`, and
+  `findById()` methods. For example, these queries return all customers with
+  their accounts:
+
+  if you process data at the repository level:
+
+  ```ts
+  customerRepository.find({include: ['accounts']});
+  ```
+
+  this is the same as the url:
+
+  ```
+  GET http://localhost:3000/customers?filter[include][]=accounts
+  ```
+
+  which returns:
+
+  ```ts
+  [
+    {
+      id: 1,
+      name: 'John',
+      accountIds: [12, 16],
+      accounts: [
+        {
+          id: 12,
+          balance: 99,
+        },
+        {
+          id: 16,
+          balance: 0,
+        },
+      ],
+    },
+    {
+      id: 2,
+      name: 'Dave',
+      accountIds: [4],
+      accounts: [
+        {
+          id: 4,
+          balance: 10,
+        },
+      ],
+    },
+  ];
+  ```
+
+- You can delete a relation from `inclusionResolvers` to disable the inclusion
+  for a certain relation. e.g
+  `customerRepository.inclusionResolvers.delete('accounts')`
+
+### Query multiple relations
+
+It is possible to query several relations or nested include relations with
+custom scope once you have the inclusion resolver of each relation set up. Check
+[HasMany - Query multiple relations](HasMany-relation.md#query-multiple-relations)
+for the usage and examples.

package/site/Relation-generator.md

@@ -138,6 +138,7 @@ The tool will prompt you for:
   - [HasManyThrough](HasManyThrough-relation.md)
   - [HasOne](HasOne-relation.md)
   - [BelongsTo](BelongsTo-relation.md)
+  - [ReferencesMany](ReferencesMany-relation.md)
 
 - Name of the source model (`sourceModel`). Prompts a list of available models
   to choose from as the source model of the relation.

package/site/Relations.md

@@ -45,6 +45,7 @@ Here are the currently supported relations:
 - [BelongsTo](BelongsTo-relation.md)
 - [HasOne](HasOne-relation.md)
 - [HasManyThrough](HasManyThrough-relation.md)
+- [ReferencesMany](ReferencesMany-relation.md)
 
 {% include note.html content="
 The `hasMany` relation may alternatively be implemented using the