Merge branch 'master' into docs/async-local-storage-recipe

Author: kamilmysliwiec

.nvmrc

@@ -1 +1 @@
-16.16.0
+18.14.0

LICENSE

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2017-2022 Kamil Myśliwiec <http://kamilmysliwiec.com>
+Copyright (c) 2017-2023 Kamil Myśliwiec <http://kamilmysliwiec.com>
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

content/cli/libraries.md

@@ -19,7 +19,7 @@ Any functionality that is suitable for re-use is a candidate for being managed a
 To get started with creating a library, run the following command:
 
 ```bash
-nest g library my-library
+$ nest g library my-library
 ```
 
 When you run the command, the `library` schematic prompts you for a prefix (AKA alias) for the library:
@@ -78,7 +78,7 @@ As with application-type projects, libraries each have their own `tsconfig.lib.j
 You can build the library with the CLI command:
 
 ```bash
-nest build my-library
+$ nest build my-library
 ```
 
 #### Using libraries

content/cli/workspaces.md

@@ -26,7 +26,7 @@ To enable monorepo mode, you start with a _standard mode_ structure, and add **p
 If we run:
 
 ```bash
-nest new my-project
+$ nest new my-project
 ```
 
 We've constructed a _standard mode_ structure, with a folder structure that looks like this:
@@ -49,8 +49,8 @@ We've constructed a _standard mode_ structure, with a folder structure that look
 We can convert this to a monorepo mode structure as follows:
 
 ```bash
-cd my-project
-nest generate app my-app
+$ cd my-project
+$ nest generate app my-app
 ```
 
 At this point, `nest` converts the existing structure to a **monorepo mode** structure. This results in a few important changes. The folder structure now looks like this:
@@ -197,8 +197,9 @@ These properties specify the compiler to use as well as various options that aff
 These properties specify the default generate options to be used by the `nest generate` command.
 
 | Property Name | Property Value Type | Description                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| ------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|---------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `spec`        | boolean _or_ object | If the value is boolean, a value of `true` enables `spec` generation by default and a value of `false` disables it. A flag passed on the CLI command line overrides this setting, as does a project-specific `generateOptions` setting (more below). If the value is an object, each key represents a schematic name, and the boolean value determines whether the default spec generation is enabled / disabled for that specific schematic. |
+| `flat`        | boolean             | If true, all generate commands will generate a flat structure                                                                                                                                                                                                                                                                                                                                                                                 |
 
 The following example uses a boolean value to specify that spec file generation should be disabled by default for all projects:
 
@@ -211,6 +212,17 @@ The following example uses a boolean value to specify that spec file generation
 }
 ```
 
+The following example uses a boolean value to specify flat file generation should be the default for all projects:
+
+```javascript
+{
+  "generateOptions": {
+    "flat": true
+  },
+  ...
+}
+```
+
 In the following example, `spec` file generation is disabled only for `service` schematics (e.g., `nest generate service...`):
 
 ```javascript

content/controllers.md

@@ -268,6 +268,8 @@ getDocs(@Query('version') version) {
 
 Routes with static paths won't work when you need to accept **dynamic data** as part of the request (e.g., `GET /cats/1` to get cat with id `1`). In order to define routes with parameters, we can add route parameter **tokens** in the path of the route to capture the dynamic value at that position in the request URL. The route parameter token in the `@Get()` decorator example below demonstrates this usage. Route parameters declared in this way can be accessed using the `@Param()` decorator, which should be added to the method signature.
 
+> info **Hint** Routes with parameters should be declared after any static paths. This prevents the parameterized paths from intercepting traffic destined for the static paths.
+
 ```typescript
 @@filename()
 @Get(':id')

content/discover/who-uses.json

@@ -268,6 +268,10 @@
     "https://polygon-software.ch",
     "https://bewith.io",
     "https://swetrix.com",
-    "https://swyftlogistics.com"
+    "https://swyftlogistics.com",
+    "https://evershop.io",
+    "https://e-design.ca",
+    "https://growthmill.com",
+    "https://tarken.com.br"
   ]
 }

content/exception-filters.md

@@ -15,7 +15,7 @@ Out of the box, this action is performed by a built-in **global exception filter
 }
 ```
 
-> info **Hint** The global exception filter partially supports the `http-errors` library. Basically, any thrown exception containing the `statusCode` and `message` property will be properly populated and send back as a response (instead of the default `InternalServerErrorException` for unrecognized exceptions).
+> info **Hint** The global exception filter partially supports the `http-errors` library. Basically, any thrown exception containing the `statusCode` and `message` properties will be properly populated and sent back as a response (instead of the default `InternalServerErrorException` for unrecognized exceptions).
 
 #### Throwing standard exceptions
 
@@ -60,16 +60,24 @@ in the `response` argument. To override the entire JSON response body, pass an o
 The second constructor argument - `status` - should be a valid HTTP status code.
 Best practice is to use the `HttpStatus` enum imported from `@nestjs/common`.
 
-Here's an example overriding the entire response body:
+There is a **third** constructor argument (optional) - `options` - that can be used to provide an error [cause](https://nodejs.org/en/blog/release/v16.9.0/#error-cause). This `cause` object is not serialized into the response object, but it can be useful for logging purposes, providing valuable information about the inner error that caused the `HttpException` to be thrown.
+
+Here's an example overriding the entire response body and providing an error cause:
 
 ```typescript
 @@filename(cats.controller)
 @Get()
 async findAll() {
-  throw new HttpException({
-    status: HttpStatus.FORBIDDEN,
-    error: 'This is a custom message',
-  }, HttpStatus.FORBIDDEN);
+  try {
+    await this.service.findAll()
+  } catch (error) { 
+    throw new HttpException({
+      status: HttpStatus.FORBIDDEN,
+      error: 'This is a custom message',
+    }, HttpStatus.FORBIDDEN, {
+      cause: error
+    });
+  }
 }
 ```
 
@@ -130,6 +138,22 @@ Nest provides a set of standard exceptions that inherit from the base `HttpExcep
 - `GatewayTimeoutException`
 - `PreconditionFailedException`
 
+All the built-in exceptions can also provide both an error `cause` and an error description using the `options` parameter:
+
+```typescript
+throw new BadRequestException('Something bad happened', { cause: new Error(), description: 'Some error description' })
+```
+
+Using the above, this is how the response would look:
+
+```json
+{
+  "message": "Something bad happened",
+  "error": "Some error description",
+  "statusCode": 400,
+}
+```
+
 #### Exception filters
 
 While the base (built-in) exception filter can automatically handle many cases for you, you may want **full control** over the exceptions layer. For example, you may want to add logging or use a different JSON schema based on some dynamic factors. **Exception filters** are designed for exactly this purpose. They let you control the exact flow of control and the content of the response sent back to the client.
@@ -182,6 +206,8 @@ export class HttpExceptionFilter {
 
 > info **Hint** All exception filters should implement the generic `ExceptionFilter<T>` interface. This requires you to provide the `catch(exception: T, host: ArgumentsHost)` method with its indicated signature. `T` indicates the type of the exception.
 
+> warning **Warning** If you are using `@nestjs/platform-fastify` you can use `response.send()` instead of `response.json()`. Don't forget to import the correct types from `fastify`.
+
 The `@Catch(HttpException)` decorator binds the required metadata to the exception filter, telling Nest that this particular filter is looking for exceptions of type `HttpException` and nothing else. The `@Catch()` decorator may take a single parameter, or a comma-separated list. This lets you set up the filter for several types of exceptions at once.
 
 #### Arguments host
@@ -323,6 +349,8 @@ export class AllExceptionsFilter implements ExceptionFilter {
 }
 ```
 
+> warning **Warning** When combining an exception filter that catches everything with a filter that is bound to a specific type, the "Catch anything" filter should be declared first to allow the specific filter to correctly handle the bound type.
+
 #### 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

@@ -10,6 +10,7 @@ Probably the most common error message is about Nest not being able to resolve d
 Nest can't resolve dependencies of the <provider> (?). Please make sure that the argument <unknown_token> at index [<index>] is available in the <module> context.
 
 Potential solutions:
+- Is <module> a valid NestJS module?
 - If <unknown_token> is a provider, is it part of the current <module>?
 - If <unknown_token> is exported from a separate @Module, is that module imported within <module>?
   @Module({
@@ -56,6 +57,7 @@ This likely happens when your project end up loading two Node modules of the pac
 Solutions:
 
 - For **Yarn** Workspaces, use the [nohoist feature](https://classic.yarnpkg.com/blog/2018/02/15/nohoist) to prevent hoisting the package `@nestjs/core`.
+- For **pnpm** Workspaces, set `@nestjs/core` as a peerDependencies in your other module and `"dependenciesMeta": {{ '{' }}"other-module-name": {{ '{' }}"injected": true{{ '}}' }}` in the app package.json where the module is imported. see: [dependenciesmetainjected](https://pnpm.io/package_json#dependenciesmetainjected)
 
 #### "Circular dependency" error
 
@@ -82,3 +84,25 @@ Along with just manually verifying your dependencies are correct, as of Nest 8.1
 <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.
+
+#### "File change detected" loops endlessly
+
+Windows users who are using TypeScript version 4.9 and up may encounter this problem.
+This happens when you're trying to run your application in watch mode, e.g `npm run start:dev` and see an endless loop of the log messages:
+
+```bash
+XX:XX:XX AM - File change detected. Starting incremental compilation...
+XX:XX:XX AM - Found 0 errors. Watching for file changes.
+```
+
+When you're using the NestJS CLI to start your application in watch mode it is done by calling `tsc --watch`, and as of version 4.9 of TypeScript, a [new strategy](https://devblogs.microsoft.com/typescript/announcing-typescript-4-9/#file-watching-now-uses-file-system-events) for detecting file changes is used which is likely to be the cause of this problem.
+In order to fix this problem, you need to add a setting to your tsconfig.json file after the `"compilerOptions"` option as follows:
+
+```bash
+  "watchOptions": {
+    "watchFile": "fixedPollingInterval"
+  }
+```
+
+This tells TypeScript to use the polling method for checking for file changes instead of file system events (the new default method), which can cause issues on some machines.
+You can read more about the `"watchFile"` option in [TypeScript documentation](https://www.typescriptlang.org/tsconfig#watch-watchDirectory).

content/faq/raw-body.md

@@ -2,6 +2,8 @@
 
 One of the most common use-case for having access to the raw request body is performing webhook signature verifications. Usually to perform webhook signature validations the unserialized request body is required to calculate an HMAC hash.
 
+> warning **Warning** This feature can be used only if the built-in global body parser middleware is enabled, ie., you must not pass `bodyParser: false` when creating the app.
+
 #### Use with Express
 
 First enable the option when creating your Nest Express application:
@@ -35,7 +37,7 @@ First enable the option when creating your Nest Fastify application:
 ```typescript
 const app = await NestFactory.create<NestFastifyApplication>(
   AppModule,
-  new FastifyAdapter()
+  new FastifyAdapter(),
   {
     rawBody: true,
   }

content/faq/request-lifecycle.md

@@ -34,7 +34,7 @@ Interceptors, for the most part, follow the same pattern as guards, with one cat
 
 #### Pipes
 
-Pipes follow the standard global to controller to route bound sequence, with the same first in first out in regards to the `@usePipes()` parameters. However, at a route parameter level, if you have multiple pipes running, they will run in the order of the last parameter with a pipe to the first. This also applies to the route level and controller level pipes. For example, if we have the following controller:
+Pipes follow the standard global to controller to route bound sequence, with the same first in first out in regards to the `@UsePipes()` parameters. However, at a route parameter level, if you have multiple pipes running, they will run in the order of the last parameter with a pipe to the first. This also applies to the route level and controller level pipes. For example, if we have the following controller:
 
 ```typescript
 @UsePipes(GeneralValidationPipe)