Merge branch 'master' of https://github.com/nestjs/docs.nestjs.com

Author: kamilmysliwiec

content/exception-filters.md

@@ -284,6 +284,8 @@ You can add as many filters with this technique as needed; simply add each to th
 
 In order to catch **every** unhandled exception (regardless of the exception type), leave the `@Catch()` decorator's parameter list empty, e.g., `@Catch()`.
 
+In the example below we have a code that is platform-agnostic because it uses the [HTTP adapter](./faq/http-adapter) to deliver the response, and doesn't use any of the platform-specific objects (`Request` and `Response`) directly:
+
 ```typescript
 import {
   ExceptionFilter,
@@ -292,30 +294,35 @@ import {
   HttpException,
   HttpStatus,
 } from '@nestjs/common';
+import { HttpAdapterHost } from '@nestjs/core';
 
 @Catch()
 export class AllExceptionsFilter implements ExceptionFilter {
-  catch(exception: unknown, host: ArgumentsHost) {
+  constructor(private readonly httpAdapterHost: HttpAdapterHost) {}
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    // In certain situations `httpAdapter` might not be available in the
+    // constructor method, thus we should resolve it here.
+    const { httpAdapter } = this.httpAdapterHost;
+
     const ctx = host.switchToHttp();
-    const response = ctx.getResponse();
-    const request = ctx.getRequest();
 
-    const status =
+    const httpStatus =
       exception instanceof HttpException
         ? exception.getStatus()
         : HttpStatus.INTERNAL_SERVER_ERROR;
 
-    response.status(status).json({
-      statusCode: status,
+    const responseBody = {
+      statusCode: httpStatus,
       timestamp: new Date().toISOString(),
-      path: request.url,
-    });
+      path: httpAdapter.getRequestUrl(ctx.getRequest()),
+    };
+
+    httpAdapter.reply(ctx.getResponse(), responseBody, httpStatus);
   }
 }
 ```
 
-In the example above the filter will catch each exception thrown, regardless of its type (class).
-
 #### Inheritance
 
 Typically, you'll create fully customized exception filters crafted to fulfill your application requirements. However, there might be use-cases when you would like to simply extend the built-in default **global exception filter**, and override the behavior based on certain factors.

content/faq/errors.md

@@ -24,6 +24,8 @@ There are a few gotchas, that are common. One is putting a provider in an `impor
 
 If you run across this error while developing, take a look at the module mentioned in the error message and look at its `providers`. For each provider in the `providers` array, make sure the module has access to all of the dependencies. Often times, `providers` are duplicated in a "Feature Module" and a "Root Module" which means Nest will try to instantiate the provider twice. More than likely, the module containing the `provider` being duplicated should be added in the "Root Module"'s `imports` array instead.
 
+If the `unknown_token` above is the string `dependency`, you might have a circular file import. This is different from the [circular dependency](./errors.md#circular-dependency-error) below because instead of  having providers depend on each other in their constructors, it just means that two files end up importing each other. A common case would be a module file declaring a token and importing a provider, and the provider import the token constant from the module file. If you are using barrel files, ensure that your barrel imports do not end up creating these circular imports as well.
+
 #### "Circular dependency" error
 
 Occasionally you'll find it difficult to avoid [circular dependencies](/fundamentals/circular-dependency) in your application. You'll need to take some steps to help Nest resolve these. Errors that arise from circular dependencies look like this:
@@ -41,3 +43,11 @@ Scope [<module_import_chain>]
 ```
 
 Circular dependencies can arise from both providers depending on each other, or typescript files depending on each other for constants, such as exporting constants from a module file and importing them in a service file. In the latter case, it is advised to create a separate file for your constants. In the former case, please follow the guide on circular dependencies and make sure that both the modules **and** the providers are marked with `forwardRef`.
+
+#### Debugging dependency errors
+
+Along with just manually verifying your dependencies are correct, as of Nest 8.1.0 you can set the `NEST_DEBUG` environment variable to a string that resolves as truthy, and get extra logging information while Nest is resolving all of the dependencies for the application. 
+
+<figure><img src="/assets/injector_logs.png" /></figure>
+
+In the above image, the string in yellow is the host class of the dependency being injected, the string in blue is the name of the injected dependency, or its injection token, and the string in purple is the module in which the dependency is being searched for. Using this, you can usually trace back the dependency resolution for what's happening and why you're getting dependency injection problems.

content/fundamentals/dependency-injection.md

@@ -137,6 +137,8 @@ What happens when your requirements go beyond those offered by _Standard provide
 
 Nest allows you to define Custom providers to handle these cases. It provides several ways to define custom providers. Let's walk through them.
 
+> info **Hint** If you are having problems with dependency resolution you can set the `NEST_DEBUG` environment variable and get extra dependency resolution logs during startup.
+
 #### Value providers: `useValue`
 
 The `useValue` syntax is useful for injecting a constant value, putting an external library into the Nest container, or replacing a real implementation with a mock object. Let's say you'd like to force Nest to use a mock `CatsService` for testing purposes.

content/fundamentals/unit-testing.md

@@ -160,6 +160,41 @@ Instead of using the production version of any provider, you can override it wit
 
 <app-banner-courses></app-banner-courses>
 
+#### Auto mocking
+
+Nest also allows you to define a mock factory to apply to all of your missing dependencies. This is useful for cases where you have a large number of dependencies in a class and mocking all of them will take a long time and a lot of setup. To make use of this feature, the `createTestingModule()` will need to be chained up with the `useMocker()` method, passing a factory for your dependency mocks. This factory can take in an optional token, which is an instance token, any token which is valid for a Nest provider, and returns a mock implementation. The below is an example of creating a generic mocker using [`jest-mock`](https://www.npmjs.com/package/jest-mock) and a specific mock for `CatsService` using `jest.fn()`.
+
+```typescript
+const moduleMocker = new ModuleMocker(global);
+
+describe('CatsController', () => {
+  let controller: CatsController;
+
+  beforeEach(async () => {
+    const moduleRef = await Test.createTestingModule({
+      controllers: [CatsController],
+    })
+    .useMocker((token) => {
+      if (token === CatsService) {
+        return { findAll: jest.fn().mockResolveValue(results) };
+      }
+      if (typeof token === 'function') {
+        const mockMetadata = moduleMocker.getMetadata(token) as MockFunctionMetadata<any, any>;
+        const Mock = moduleMocker.generateFromMetadata(mockMetadata);
+        return new Mock();
+      }
+    })
+    .compile();
+    
+    controller = moduleRef.get(CatsController);
+  });
+})
+```
+
+> info **Hint** A general mock factory, like `createMock` from [`@golevelup/ts-jest`](https://github.com/golevelup/nestjs/tree/master/packages/testing) can also be passed directly.
+
+You can also retrieve these mocks out of the testing container as you normally would custom providers, `moduleRef.get(CatsService)`.
+
 #### End-to-end testing
 
 Unlike unit testing, which focuses on individual modules and classes, end-to-end (e2e) testing covers the interaction of classes and modules at a more aggregate level -- closer to the kind of interaction that end-users will have with the production system. As an application grows, it becomes hard to manually test the end-to-end behavior of each API endpoint. Automated end-to-end tests help us ensure that the overall behavior of the system is correct and meets project requirements. To perform e2e tests we use a similar configuration to the one we just covered in **unit testing**. In addition, Nest makes it easy to use the [Supertest](https://github.com/visionmedia/supertest) library to simulate HTTP requests.
@@ -243,26 +278,27 @@ describe('Cats', () => {
 >
 > ```ts
 > let app: NestFastifyApplication;
-> 
+>
 > beforeAll(async () => {
 >   app = moduleRef.createNestApplication<NestFastifyApplication>(
 >     new FastifyAdapter(),
 >   );
 >
 >   await app.init();
 >   await app.getHttpAdapter().getInstance().ready();
-> })
-> 
+> });
+>
 > it(`/GET cats`, () => {
 >   return app
 >     .inject({
 >       method: 'GET',
->       url: '/cats'
->     }).then(result => {
->       expect(result.statusCode).toEqual(200)
->       expect(result.payload).toEqual(/* expectedPayload */)
+>       url: '/cats',
+>     })
+>     .then((result) => {
+>       expect(result.statusCode).toEqual(200);
+>       expect(result.payload).toEqual(/* expectedPayload */);
 >     });
-> })
+> });
 > ```
 
 In this example, we build on some of the concepts described earlier. In addition to the `compile()` method we used earlier, we now use the `createNestApplication()` method to instantiate a full Nest runtime environment. We save a reference to the running app in our `app` variable so we can use it to simulate HTTP requests.

content/graphql/federation.md

@@ -18,7 +18,7 @@ In the next example, we'll set up a demo application with a gateway and two fede
 First, install the optional dependency for federation:
 
 ```bash
-$ npm install --save @apollo/federation
+$ npm install --save @apollo/federation @apollo/subgraph
 ```
 
 #### Schema first

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 @nestjs/graphql graphql apollo-server-express
+$ npm i @nestjs/graphql graphql@^15 apollo-server-express
 ```
 
 > info **Hint** If using Fastify, instead of installing `apollo-server-express`, you should install `apollo-server-fastify`.

content/introduction.md

@@ -34,6 +34,8 @@ $ npm install
 $ npm run start
 ```
 
+> info **Hint** If you'd like to clone the repository without the git history, you can use [degit](https://github.com/Rich-Harris/degit).
+
 Open your browser and navigate to [`http://localhost:3000/`](http://localhost:3000/).
 
 To install the JavaScript flavor of the starter project, use `javascript-starter.git` in the command sequence above.

content/microservices/grpc.md

@@ -427,7 +427,7 @@ bidiHello(messages: Observable<any>, metadata: Metadata, call: ServerDuplexStrea
 
 > info **Hint** The `Metadata` and `ServerUnaryCall` classes/interfaces are imported from the `grpc` package.
 
-According to the service definition (in the `.proto` file), the `BidiHello` method should stream requests to the service. To send multiple asynchronous messages to the stream from a client, we leverage an RxJS `ReplySubject` class.
+According to the service definition (in the `.proto` file), the `BidiHello` method should stream requests to the service. To send multiple asynchronous messages to the stream from a client, we leverage an RxJS `ReplaySubject` class.
 
 ```typescript
 const helloService = this.client.getService<HelloService>('HelloService');

content/modules.md

@@ -8,24 +8,12 @@ Each application has at least one module, a **root module**. The root module is
 
 The `@Module()` decorator takes a single object whose properties describe the module:
 
-<table>
-  <tr>
-    <td><code>providers</code></td>
-    <td>the providers that will be instantiated by the Nest injector and that may be shared at least across this module</td>
-  </tr>
-  <tr>
-    <td><code>controllers</code></td>
-    <td>the set of controllers defined in this module which have to be instantiated</td>
-  </tr>
-  <tr>
-    <td><code>imports</code></td>
-    <td>the list of imported modules that export the providers which are required in this module</td>
-  </tr>
-  <tr>
-    <td><code>exports</code></td>
-    <td>the subset of <code>providers</code> that are provided by this module and should be available in other modules which import this module</td>
-  </tr>
-</table>
+| | |
+|-|-|
+| `providers`   | the providers that will be instantiated by the Nest injector and that may be shared at least across this module |
+| `controllers` | the set of controllers defined in this module which have to be instantiated  |
+| `imports`     | the list of imported modules that export the providers which are required in this module |
+| `exports`     | the subset of `providers` that are provided by this module and should be available in other modules which import this module. You can use either the provider itself or just its token (`provide` value) |
 
 The module **encapsulates** providers by default. This means that it's impossible to inject providers that are neither directly part of the current module nor exported from the imported modules. Thus, you may consider the exported providers from a module as the module's public interface, or API.
 

content/security/csrf.md

@@ -10,12 +10,13 @@ Start by installing the required package:
 $ npm i --save csurf
 ```
 
-> warning **Warning** As explained on the [csurf middleware page](https://github.com/expressjs/csurf#csurf), the csurf module requires either session middleware or a cookie-parser to be initialized first. Please see that documentation for further instructions.
+> warning **Warning** As explained in the [`csurf` docs](https://github.com/expressjs/csurf#csurf), this middleware requires either session middleware or `cookie-parser` to be initialized first. Please see that documentation for further instructions.
 
-Once the installation is complete, apply the csurf middleware as global middleware.
+Once the installation is complete, apply the `csurf` middleware as global middleware.
 
 ```typescript
 import * as csurf from 'csurf';
+// ...
 // somewhere in your initialization file
 app.use(csurf());
 ```
@@ -32,6 +33,9 @@ Once the installation is complete, register the `fastify-csrf` plugin, as follow
 
 ```typescript
 import fastifyCsrf from 'fastify-csrf';
-// somewhere in your initialization file
+// ...
+// somewhere in your initialization file after registering some storage plugin
 app.register(fastifyCsrf);
 ```
+
+> warning **Warning** As explained in the `fastify-csrf` docs [here](https://github.com/fastify/fastify-csrf#usage), this plugin requires a storage plugin to be initialized first. Please, see that documentation for further instructions.