@loopback/docs 4.0.3 → 5.1.0

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.1.0](https://github.com/loopbackio/loopback-next/compare/@loopback/docs@5.0.0...@loopback/docs@5.1.0) (2022-06-13)
+
+
+### Features
+
+* **cli:** add option to create relations in cli discover command ([37a5f73](https://github.com/loopbackio/loopback-next/commit/37a5f73ada12b64035ef32b01411c28d72058887))
+* **cli:** add option to mark id field as not required in discover command ([497b21d](https://github.com/loopbackio/loopback-next/commit/497b21d84d970a8dcc714d059108cabdf99d46e0))
+* **rest-crud:** add option to create readonly rest-crud apis ([6ae1423](https://github.com/loopbackio/loopback-next/commit/6ae142302ca61363a357559ba42243bdaf4f7256))
+
+
+
+
+
+## [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

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/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) IBM Corp. 2017,2020.
+Copyright (c) IBM Corp. and LoopBack contributors 2017,2020.
 Node module: @loopback/docs
 This project is licensed under the MIT License, full text below.
 
@@ -6,7 +6,7 @@ This project is licensed under the MIT License, full text below.
 
 MIT License
 
-MIT License Copyright (c) IBM Corp. 2017,2020
+MIT License Copyright (c) IBM Corp. and LoopBack contributors 2017,2020
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@loopback/docs",
   "description": "Documentation files rendered at [https://loopback.io](https://loopback.io)",
-  "version": "4.0.3",
+  "version": "5.1.0",
   "keywords": [
     "LoopBack",
     "docs"
   ],
   "license": "MIT",
-  "author": "IBM Corp.",
-  "copyright.owner": "IBM Corp.",
+  "author": "IBM Corp. and LoopBack contributors",
+  "copyright.owner": "IBM Corp. and LoopBack contributors",
   "homepage": "https://github.com/loopbackio/loopback-next/tree/master/docs",
   "repository": {
     "type": "git",
@@ -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.1",
-    "tslib": "^2.3.1"
+    "fs-extra": "^10.1.0",
+    "tslib": "^2.4.0"
   },
   "devDependencies": {
-    "@loopback/build": "^8.1.1"
+    "@loopback/build": "^9.0.1"
   },
-  "gitHead": "8aff2ce33aad3daa53b05fa0fbe8a1b2c7ad0bdf"
+  "gitHead": "ccf7863d0639de966d6c6129b4aa94ba1dce2c33"
 }

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/Copyright-generator.md

@@ -22,7 +22,7 @@ lb4 copyright [options]
 The following is an example of such headers.
 
 ```js
-// Copyright IBM Corp. 2020. All Rights Reserved.
+// Copyright IBM Corp. and LoopBack contributors 2020. All Rights Reserved.
 // Node module: @loopback/cli
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
@@ -35,7 +35,8 @@ Please note the command expects `git` is installed.
 
 ### Options
 
-`--owner` : _(Optional)_ The owner of the copyright, such as `IBM Corp.`.
+`--owner` : _(Optional)_ The owner of the copyright, such as
+`IBM Corp. and LoopBack contributors`.
 
 `--license` : _(Optional)_ The name of the license, such as `MIT`.
 
@@ -74,15 +75,15 @@ The command prompts you for:
    directory of your package, its content will be read as the license header
    template without prompting.
 
-The default owner is `IBM Corp.` and license is `MIT` with the following
-`package.json`.
+The default owner is `IBM Corp. and LoopBack contributors` and license is `MIT`
+with the following `package.json`.
 
 ```json
 {
   "name": "@loopback/boot",
   "version": "2.0.2",
-  "author": "IBM Corp.",
-  "copyright.owner": "IBM Corp.",
+  "author": "IBM Corp. and LoopBack contributors",
+  "copyright.owner": "IBM Corp. and LoopBack contributors",
   "license": "MIT"
 }
 ```
@@ -93,7 +94,7 @@ The following output is captured when `lb4 copyright` is run against
 [`loopback4-example-shopping`](https://github.com/loopbackio/loopback4-example-shopping).
 
 ```
-? Copyright owner: IBM Corp.
+? Copyright owner: IBM Corp. and LoopBack contributors
 ? License name: (Use arrow keys or type to search)
 ❯ MIT (MIT License)
   ISC (ISC License)

package/site/Discovering-models.md

@@ -39,6 +39,8 @@ Models can be discovered from a supported datasource by running the
 
 `--views`: Choose whether to discover views. Default is true
 
+`--relations`: Choose whether to create relations. Default is false
+
 `--all`: Skips the model prompt and discovers all of them
 
 `--outDir`: Specify the directory into which the `model.model.ts` files will be
@@ -47,6 +49,9 @@ placed. Default is `src/models`
 `--schema`: Specify the schema which the datasource will find the models to
 discover
 
+`--optionalId`: Specify if the Id property of generated models will be marked as
+not required
+
 ### Interactive Prompts
 
 Based on the option, the tool may prompt you for:

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-relation.md

@@ -0,0 +1,123 @@
+---
+lang: en
+title: 'Polymorphic Relation'
+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.