Merge branch 'master' into patch-1

Author: kamilmysliwiec

.github/workflows/lighthouse.yml

@@ -0,0 +1,39 @@
+name: Lighthouse
+
+on:
+  pull_request:
+    paths-ignore:
+    - 'content/**/*.md'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v1
+      - name: Use Node.js 12.x
+        uses: actions/setup-node@v1
+        with:
+          node-version: 12.x
+      # Build needs around 400 seconds on Netlify.
+      # We can not rely on "Waiting for 200", since the user
+      # might push another commit to an existing PR, meaning
+      # the deploy preview is already online.
+      - name: Sleep 400 seconds
+        run: sleep 400
+      - name: Waiting for 200 from the Netlify Preview
+        uses: jakepartusch/wait-for-netlify-action@v1
+        id: wait-for-netflify-preview
+        with:
+          site_name: 'docs-nestjs'
+          max_timeout: 600
+      - name: Run Lighthouse on urls and validate with lighthouserc
+        uses: treosh/lighthouse-ci-action@v2
+        with:
+          urls: |
+            ${{ steps.wait-for-netflify-preview.outputs.url }}
+            ${{ steps.wait-for-netflify-preview.outputs.url }}/first-steps
+          runs: 5
+          configPath: './lighthouserc.json'
+          uploadArtifacts: true
+          temporaryPublicStorage: true

.nvmrc

@@ -1 +1 @@
-12.17.0
+12.18.1

content/cli/scripts.md

@@ -10,7 +10,7 @@ A Nest application is a **standard** TypeScript application that needs to be com
 
 This goal is accomplished through a combination of the `nest` command, a locally installed TypeScript compiler, and `package.json` scripts. We describe how these technologies work together below. This should help you understand what's happening at each step of the build/execute process, and how to customize that behavior if necessary.
 
-### The nest binary
+#### The nest binary
 
 The `nest` command is an OS level binary (i.e., runs from the OS command line). This command actually encompasses 3 distinct areas, described below. We recommend that you run the build (`nest build`) and execution (`nest start`) sub-commands via the `package.json` scripts provided automatically when a project is scaffolded (see [typescript starter](https://github.com/nestjs/typescript-starter) if you wish to start by cloning a repo, instead of running `nest new`).
 
@@ -30,7 +30,7 @@ See the [nest start](https://docs.nestjs.com/cli/usages#nest-start) documentatio
 
 The `nest generate` commands, as the name implies, generate new Nest projects, or components within them.
 
-### Package scripts
+#### Package scripts
 
 Running the `nest` commands at the OS command level requires that the `nest` binary be installed globally. This is a standard feature of npm, and outside of Nest's direct control. One consequence of this is that the globally installed `nest` binary is **not** managed as a project dependency in `package.json`. For example, two different developers can be running two different versions of the `nest` binary. The standard solution for this is to use package scripts so that you can treat the tools used in the build and execute steps as development dependencies.
 
@@ -54,11 +54,11 @@ These commands use npm's script running capabilities to execute `nest build` or
 
 For most developers/teams, it is recommended to utilize the package scripts for building and executing their Nest projects. You can fully customize the behavior of these scripts via their options (`--path`, `--webpack`, `--webpackPath`) and/or customize the `tsc` or webpack compiler options files (e.g., `tsconfig.json`) as needed. You are also free to run a completely custom build process to compile the TypeScript (or even to execute TypeScript directly with `ts-node`).
 
-### Backward compatibility
+#### Backward compatibility
 
 Because Nest applications are pure TypeScript applications, previous versions of the Nest build/execute scripts will continue to operate. You are not required to upgrade them. You can choose to take advantage of the new `nest build` and `nest start` commands when you are ready, or continue running previous or customized scripts.
 
-### Migration
+#### Migration
 
 While you are not required to make any changes, you may want to migrate to using the new CLI commands instead of using tools such as `tsc-watch` or `ts-node`. In this case, simply install the latest version of the `@nestjs/cli`, both globally and locally:
 

content/controllers.md

@@ -442,37 +442,38 @@ export class CatsController {
   }
 }
 @@switch
-import { Controller, Get, Query, Post, Body, Put, Param, Delete } from '@nestjs/common';
+import { Controller, Get, Query, Post, Body, Put, Param, Delete, Bind } from '@nestjs/common';
 
 @Controller('cats')
 export class CatsController {
   @Post()
   @Bind(Body())
-  create(@Body() createCatDto) {
+  create(createCatDto) {
     return 'This action adds a new cat';
   }
 
   @Get()
   @Bind(Query())
-  findAll(@Query() query) {
+  findAll(query) {
+    console.log(query);
     return `This action returns all cats (limit: ${query.limit} items)`;
   }
 
   @Get(':id')
   @Bind(Param('id'))
-  findOne(@Param('id') id) {
+  findOne(id) {
     return `This action returns a #${id} cat`;
   }
 
   @Put(':id')
   @Bind(Param('id'), Body())
-  update(@Param('id') id, @Body() updateCatDto) {
+  update(id, updateCatDto) {
     return `This action updates a #${id} cat`;
   }
 
   @Delete(':id')
   @Bind(Param('id'))
-  remove(@Param('id') id) {
+  remove(id) {
     return `This action removes a #${id} cat`;
   }
 }

content/custom-decorators.md

@@ -5,7 +5,7 @@ Nest is built around a language feature called **decorators**. Decorators are a
 <blockquote class="external">
   An ES2016 decorator is an expression which returns a function and can take a target, name and property descriptor as arguments.
   You apply it by prefixing the decorator with an <code>@</code> character and placing this at the very top of what
-  you are trying to decorate. Decorators can be defined for either a class or a property.
+  you are trying to decorate. Decorators can be defined for either a class, a method or a property.
 </blockquote>
 
 #### Param decorators

content/discover/who-uses.json

@@ -152,6 +152,10 @@
       "url": "https://bedu.org",
       "width": "100px"
     },
+    {
+      "logo": "/assets/logo/shopback.png",
+      "url": "https://shopback.com"
+    },
     {
       "logo": "/assets/logo/facile.png",
       "url": "https://www.facile.it",
@@ -201,6 +205,7 @@
     "https://www.mediktiv.com",
     "https://harmonize.health",
     "https://accerlery.be",
-    "https://www.facile.it"
+    "https://www.facile.it",
+    "https://shopback.com"
   ]
 }

content/fundamentals/lifecycle-events.md

@@ -8,8 +8,6 @@ The following diagram depicts the sequence of key application lifecycle events,
 
 <figure><img src="/assets/lifecycle-events.png" /></figure>
 
-<p style="clear: both;"></p>
-
 #### Lifecycle events
 
 Lifecycle events happen during application bootstrapping and shutdown. Nest calls registered lifecycle hook methods on `modules`, `injectables` and `controllers` at each of the following lifecycle events (**shutdown hooks** need to be enabled first, as described [below](https://docs.nestjs.com/fundamentals/lifecycle-events#application-shutdown)). As shown in the diagram above, Nest also calls the appropriate underlying methods to begin listening for connections, and to stop listening for connections.
@@ -24,7 +22,9 @@ In the following table, `onModuleDestroy`, `beforeApplicationShutdown` and `onAp
 | `beforeApplicationShutdown()`\* | Called after all `onModuleDestroy()` handlers have completed (Promises resolved or rejected);<br />once complete (Promises resolved or rejected), all existing connections will be closed (`app.close()` called). |
 | `onApplicationShutdown()`\*     | Called after connections close (`app.close()` resolves.                                                                                                                                                           |
 
-\* For these events, if you're not calling `app.close()` explicitly, you must opt-in to make them work with system signals such as `SIGTERM`.  See [Application shutdown](#application-shutdown) below.
+\* For these events, if you're not calling `app.close()` explicitly, you must opt-in to make them work with system signals such as `SIGTERM`. See [Application shutdown](#application-shutdown) below.
+
+> warning **Warning** The lifecycle hooks listed above are not triggered for **request-scoped** classes. Request-scoped classes are not tied to the application lifecycle and their lifespan is unpredictable. They are exclusively created for each request and automatically garbage-collected after the response is sent.
 
 #### Usage
 

content/graphql/complexity.md

@@ -0,0 +1,86 @@
+### Complexity
+
+> warning **Warning** This chapter applies only to the code first approach.
+
+Query complexity allows you to define how complex certain fields are, and to restrict queries with a **maximum complexity**. The idea is to define how complex each field is by using a simple number. A common default is to give each field a complexity of `1`. In addition, the complexity calculation of a GraphQL query can be customized with so-called complexity estimators. A complexity estimator is a simple function that calculates the complexity for a field. You can add any number of complexity estimators to the rule, which are then executed one after another. The first estimator that returns a numeric complexity value determines the complexity for that field.
+
+The `@nestjs/graphql` package integrates very well with tools like [graphql-query-complexity](https://github.com/slicknode/graphql-query-complexity) that provides a cost analysis-based solution. With this library, you can reject queries to your GraphQL server that are deemed too costly to execute.
+
+#### Installation
+
+To begin using it, we first install the required dependency.
+
+```bash
+$ npm install --save graphql-query-complexity
+```
+
+#### Getting started
+
+Once the installation process is complete, we can define the `ComplexityPlugin` class:
+
+```typescript
+import { GraphQLSchemaHost, Plugin } from '@nestjs/graphql';
+import {
+  ApolloServerPlugin,
+  GraphQLRequestListener,
+} from 'apollo-server-plugin-base';
+import { GraphQLError } from 'graphql';
+import {
+  fieldExtensionsEstimator,
+  getComplexity,
+  simpleEstimator,
+} from 'graphql-query-complexity';
+
+@Plugin()
+export class ComplexityPlugin implements ApolloServerPlugin {
+  constructor(private gqlSchemaHost: GraphQLSchemaHost) {}
+
+  requestDidStart(): GraphQLRequestListener {
+    const { schema } = this.gqlSchemaHost;
+
+    return {
+      didResolveOperation({ request, document }) {
+        const complexity = getComplexity({
+          schema,
+          operationName: request.operationName,
+          query: document,
+          variables: request.variables,
+          estimators: [
+            fieldExtensionsEstimator(),
+            simpleEstimator({ defaultComplexity: 1 }),
+          ],
+        });
+        if (complexity >= 20) {
+          throw new GraphQLError(
+            `Query is too complex: ${complexity}. Maximum allowed complexity: 20`,
+          );
+        }
+        console.log('Query Complexity:', complexity);
+      },
+    };
+  }
+}
+```
+
+For demonstration purposes, we specified the maximum allowed complexity as `20`. In the example above, we used 2 estimators, the `simpleEstimator` and the `fieldExtensionsEstimator`.
+
+- `simpleEstimator`: the simple estimator returns a fixed complexity for each field
+- `fieldExtensionsEstimator`: the field extensions estimator extracts the complexity value for each field of your schema
+
+> info **Hint** Remember to add this class to the providers array in any module.
+
+#### Field-level complexity
+
+With this plugin in place, we can now define the complexity for any field by specifying the `complexity` property in the options object passed into the `@Field()` decorator, as follows:
+
+```typescript
+@Field({ complexity: 3 })
+title: string;
+```
+
+Alternatively, you can define the estimator function:
+
+```typescript
+@Field({ complexity: (options: ComplexityEstimatorArgs) => ... })
+title: string;
+```

content/graphql/extensions.md

@@ -0,0 +1,64 @@
+### Extensions
+
+> warning **Warning** This chapter applies only to the code first approach.
+
+Extensions is an **advanced, low-level feature** that lets you define arbitrary data in the types configuration. Attaching custom metadata to certain fields allows you to create more sophisticated, generic solutions. For example, with extensions, you can define field-level roles required to access particular fields. Such roles can be reflected at runtime to determine whether the caller has sufficient permissions to retrieve a specific field.
+
+#### Adding custom metadata
+
+To attach custom metadata for a field, use the `@Extensions()` decorator exported from the `@nestjs/graphql` package.
+
+```typescript
+@Field()
+@Extensions({ role: Role.ADMIN })
+password: string;
+```
+
+In the example above, we assigned the `role` metadata property the value of `Role.ADMIN`.  `Role` is a simple TypeScript enum that groups all the user roles available in our system.
+
+Note, in addition to setting metadata on fields, you can use the `@Extensions()` decorator at the class level and method level (e.g., on the query handler).
+
+#### Using custom metadata
+
+The logic that leverages the custom metatada can be as complex as needed. For example, you can create a simple interceptor that stores/logs events per method invocation, or create a sophisticated guard that **analyzes requested fields**, iterates through the `GraphQLObjectType` definition, and matches the roles required to retrieve specific fields with the caller permissions (field-level permissions system).
+
+Let's define a `FieldRolesGuard` that implements a basic version of such a field-level permissions system.
+
+```typescript
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { GqlExecutionContext } from '@nestjs/graphql';
+import { GraphQLNonNull, GraphQLObjectType, GraphQLResolveInfo } from 'graphql';
+import * as graphqlFields from 'graphql-fields';
+
+@Injectable()
+export class FieldRolesGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const info = GqlExecutionContext.create(context).getInfo<
+      GraphQLResolveInfo
+    >();
+    const returnType = (info.returnType instanceof GraphQLNonNull
+      ? info.returnType.ofType
+      : info.returnType) as GraphQLObjectType;
+
+    const fields = returnType.getFields();
+    const requestedFields = graphqlFields(info);
+
+    Object.entries(fields)
+      .filter(([key]) => key in requestedFields)
+      .map(([_, field]) => field)
+      .filter((field) => field.extensions && field.extensions.role)
+      .forEach((field) => {
+        // match user and field roles here
+        console.log(field.extensions.role);
+      });
+
+    return true;
+  }
+}
+```
+
+> warning **Warning** For illustration purposes, we assumed that **every** resolver returns either the `GraphQLObjectType` or `GraphQLNonNull` that wraps the object type. In a real-world application, you should cover other cases (scalars, etc.). Note that using this particular implementation can lead to unexpected errors (e.g., missing `getFields()` method).
+
+In the example above, we've used the [graphql-fields](https://github.com/robrichard/graphql-fields) package that turns the `GraphQLResolveInfo` object into an object that consists of the requested fields. We used this specific library to make the presented example somewhat simpler.
+
+With this guard in place, if the return type of any resolver contains a field annotated with the `@Extensions({{ '{' }} role: Role.ADMIN {{ '}' }}})` decorator, this `role` (`Role.ADMIN`) will be logged in the console **if requested** in the GraphQL query.

content/graphql/quick-start.md

@@ -9,7 +9,7 @@ In this chapter, we assume a basic understanding of GraphQL, and focus on how to
 Start by installing the required packages:
 
 ```bash
-$ npm i --save @nestjs/graphql graphql-tools graphql
+$ npm i @nestjs/graphql graphql-tools graphql
 ```
 
 Depending on what underlying platform you use (Express or Fastify), you must also install either `apollo-server-express` or `apollo-server-fastify`.
@@ -169,6 +169,24 @@ definitionsFactory.generate({
 });
 ```
 
+To automatically generate the additional `__typename` field for every object type, enable the `emitTypenameField` option.
+
+```typescript
+definitionsFactory.generate({
+  // ...,
+  emitTypenameField: true,
+});
+```
+
+To generate resolvers (queries, mutations, subscriptions) as plain fields without arguments, enable the `skipResolverArgs` option.
+
+```typescript
+definitionsFactory.generate({
+  // ...,
+  skipResolverArgs: true,
+});
+```
+
 A fully working schema first sample is available [here](https://github.com/nestjs/nest/tree/master/sample/12-graphql-schema-first).
 
 #### Accessing generated schema