Skip to content

Commit 3d1ffd1

Browse files
kamilmysliwieckamilmysliwiec
committed
Merge branch 'master' into feat/mapped-types-generator
2 parents daa02f1 + d63c2f6 commit 3d1ffd1

File tree

9 files changed

+486
-276
lines changed

9 files changed

+486
-276
lines changed

‎content/components.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -203,3 +203,11 @@ This is how our directory structure should look now:
203203
<div class="item">main.ts</div>
204204
</div>
205205
</div>
206+
207+
#### Manual instantiation
208+
209+
Thus far, we've discussed how Nest automatically handles most of the details of resolving dependencies. In certain circumstances, you may need to step outside of the built-in Dependency Injection system and manually retrieve or instantiate providers. We briefly discuss two such topics below.
210+
211+
To get existing instances, or instantiate providers dynamically, you can use [Module reference](https://docs.nestjs.com/fundamentals/module-ref).
212+
213+
To get providers within the `bootstrap()` function (for example for standalone applications without controllers, or to utilize a configuration service during bootstrapping) see [Standalone applications](https://docs.nestjs.com/standalone-applications).

‎content/fundamentals/lifecycle-events.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ The following diagram depicts the sequence of key application lifecycle events,
1515
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.
1616

1717
| Lifecycle hook method | Lifecycle event triggering the hook method call |
18-
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
18+
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
1919
| `onModuleInit()` | Called once the host module's dependencies have been resolved. |
2020
| `onApplicationBootstrap()` | Called once all modules have been initialized, but before listening for connections. |
2121
| `onModuleDestroy()` | Called after a termination signal (e.g., `SIGTERM`) has been received. |
@@ -66,6 +66,8 @@ async onModuleInit() {
6666

6767
The `beforeApplicationShutdown()` and `onApplicationShutdown()` hooks are called in the **terminating** phase (in response to system signals such as `SIGTERM`). This feature is often used with [Kubernetes](https://kubernetes.io/), [Heroku](https://www.heroku.com/) or similar services.
6868

69+
> warning **warning** Due to inherent platform limitations, NestJS has limited support for application shutdown hooks on Windows. You can expect `SIGINT` to work, as well as `SIGBREAK` and to some extent `SIGHUP` - [read more](https://nodejs.org/api/process.html#process_signal_events). However `SIGTERM` will never work on Windows because killing a process in the task manager is unconditional, "i.e., there's no way for an application to detect or prevent it". Here's some [relevant documentation](http://docs.libuv.org/en/v1.x/signal.html) from libuv to learn more about how `SIGINT`, `SIGBREAK` and others are handled on Windows. Also, see Node.js documentation of [Process Signal Events](https://nodejs.org/api/process.html#process_signal_events)
70+
6971
To use these hooks you must activate a listener which listens to shutdown signals.
7072

7173
```typescript
@@ -81,6 +83,8 @@ async function bootstrap() {
8183
bootstrap();
8284
```
8385

86+
> info **Info** `enableShutdownHooks` consumes memory by starting listeners. In cases where you are running multiple Nest apps in a single Node process (e.g., when running parallel tests with Jest), Node may complain about excessive listener processes. For this reason, `enableShutdownHooks` is not enabled by default. Be aware of this condition when you are running multiple instances in a single Node process.
87+
8488
When the application receives a termination signal it will call any registered `beforeApplicationShutdown()`, then `onApplicationShutdown()` methods (in the sequence described above) with the corresponding signal as the first parameter. If a registered function awaits an asynchronous call (returns a promise), Nest will not continue in the sequence until the promise is resolved or rejected.
8589

8690
```typescript

‎content/graphql/enums.md

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -64,13 +64,22 @@ export enum AllowedColor {
6464
}
6565
```
6666

67-
Sometimes a backend forces a different value for an enum internally than in the public API. In this example the API contains `RED`, however in resolvers we may use `#f00` instead (read more [here](https://www.apollographql.com/docs/apollo-server/schema/scalars-enums/#internal-values)). To accomplish this, declare a resolver class for the `AllowedColor` enum:
67+
Sometimes a backend forces a different value for an enum internally than in the public API. In this example the API contains `RED`, however in resolvers we may use `#f00` instead (read more [here](https://www.apollographql.com/docs/apollo-server/schema/scalars-enums/#internal-values)). To accomplish this, declare a resolver object for the `AllowedColor` enum:
6868

6969
```typescript
70-
@Resolver('AllowedColor')
71-
export class AllowedColorResolver {
72-
[AllowedColor.RED]: '#f00';
70+
export const allowedColorResolver: Record<keyof typeof AllowedColor, any> = {
71+
RED: '#f00',
7372
}
7473
```
7574

7675
> info **Hint** All decorators are exported from the `@nestjs/graphql` package.
76+
77+
Then use this resolver object together with the `resolvers` property of the `GraphQLModule#forRoot()` method, as follows:
78+
79+
```typescript
80+
GraphQLModule.forRoot({
81+
resolvers: {
82+
AllowedColor: allowedColorResolver,
83+
},
84+
})
85+
```

‎content/migration.md

Lines changed: 159 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,164 @@ In order to migrate your existing application, simply rename all the `type-graph
7171
- use `Type` (imported from `@nestjs/common`) instead of `ClassType` (imported from `type-graphql`)
7272
- move methods that require `@Args()` from object types (classes annotated with `@ObjectType()` decorator) under resolver classes (and use `@ResolveField()` decorator instead of `@Field()`)
7373

74+
#### Terminus
75+
76+
In the version 7 major release of `@nestjs/terminus`, a new simplified API has been introduced
77+
to run health checks. The previously required peer dependency `@godaddy/terminus` has been removed, which allows us to integrate our health checks automatically into Swagger! Read more about the removal of `@godaddy/terminus` [here](https://github.com/nestjs/terminus/issues/340).
78+
79+
For most users, the biggest change will be the removal of the `TerminusModule.forRootAsync` function. With the next major version, this function will be completely removed.
80+
To migrate to the new API, you will need to create a new controller, which will handle your health checks.
81+
82+
```typescript
83+
@@filename()
84+
// Before
85+
@Injectable()
86+
export class TerminusOptionsService implements TerminusOptionsFactory {
87+
constructor(
88+
private dns: DNSHealthIndicator,
89+
) {}
90+
91+
createTerminusOptions(): TerminusModuleOptions {
92+
const healthEndpoint: TerminusEndpoint = {
93+
url: '/health',
94+
healthIndicators: [
95+
async () => this.dns.pingCheck('google', 'https://google.com'),
96+
],
97+
};
98+
return {
99+
endpoints: [healthEndpoint],
100+
};
101+
}
102+
}
103+
104+
@Module({
105+
imports: [
106+
TerminusModule.forRootAsync({
107+
useClass: TerminusOptionsService
108+
})
109+
]
110+
})
111+
export class AppModule { }
112+
113+
// After
114+
@Controller('health')
115+
export class HealthController {
116+
constructor(
117+
private health: HealthCheckService,
118+
private dns: DNSHealthIndicator,
119+
) { }
120+
121+
@Get()
122+
@HealthCheck()
123+
healthCheck() {
124+
return this.health.check([
125+
async () => this.dns.pingCheck('google', 'https://google.com'),
126+
]);
127+
}
128+
}
129+
130+
@Module({
131+
imports: [
132+
TerminusModule
133+
]
134+
})
135+
export class AppModule { }
136+
137+
@@switch
138+
139+
// Before
140+
@Injectable()
141+
@Dependencies(DNSHealthIndicator)
142+
export class TerminusOptionsService {
143+
constructor(
144+
private dns,
145+
) {}
146+
147+
createTerminusOptions() {
148+
const healthEndpoint = {
149+
url: '/health',
150+
healthIndicators: [
151+
async () => this.dns.pingCheck('google', 'https://google.com'),
152+
],
153+
};
154+
return {
155+
endpoints: [healthEndpoint],
156+
};
157+
}
158+
}
159+
160+
@Module({
161+
imports: [
162+
TerminusModule.forRootAsync({
163+
useClass: TerminusOptionsService
164+
})
165+
]
166+
})
167+
export class AppModule { }
168+
169+
// After
170+
@Controller('/health')
171+
@Dependencies(HealthCheckService, DNSHealthIndicator)
172+
export class HealthController {
173+
constructor(
174+
private health,
175+
private dns,
176+
) { }
177+
178+
@Get('/')
179+
@HealthCheck()
180+
healthCheck() {
181+
return this.health.check([
182+
async () => this.dns.pingCheck('google', 'https://google.com'),
183+
])
184+
}
185+
}
186+
187+
@Module({
188+
controllers: [
189+
HealthController
190+
],
191+
imports: [
192+
TerminusModule
193+
]
194+
})
195+
export class AppModule { }
196+
```
197+
198+
> warning **Warning** If you have set a [Global Prefix](faq#global-prefix) in your Nest application and you have not used the `useGlobalPrefix` Terminus option, the URL of your health check will change. Make sure to update the reference to that URL, or use the legacy Terminus API until [nestjs/nest#963](https://github.com/nestjs/nest/issues/963) is fixed.
199+
200+
If you are forced to use the legacy API, you can also disable deprecation messages for the time being.
201+
202+
```typescript
203+
TerminusModule.forRootAsync({
204+
useFactory: () => ({
205+
disableDeprecationWarnings: true,
206+
endpoints: [
207+
// ...
208+
]
209+
})
210+
}
211+
```
212+
213+
You should enable shutdown hooks in your `main.ts` file. The Terminus integration will listen on POSIX signals such as SIGTERM (see the [Application shutdown chapter](fundamentals/lifecycle-events#application-shutdown) for more information). When enabled, the health check route(s) will automatically respond with a Service Unavailable (503) HTTP error response when the server is shutting down.
214+
215+
With the removal of `@godaddy/terminus`, you will need to update your `import` statements
216+
to use `@nestjs/terminus` instead. Most notable is the import of the `HealthCheckError`.
217+
218+
```typescript
219+
@@filename(custom.health)
220+
// Before
221+
import { HealthCheckError } from '@godaddy/terminus';
222+
// After
223+
import { HealthCheckError } from '@nestjs/terminus';
224+
```
225+
226+
Once you have fully migrated, make sure you uninstall `@godaddy/terminus`.
227+
228+
```bash
229+
npm uninstall --save @godaddy/terminus
230+
```
231+
74232
#### HTTP exceptions body
75233
76234
Previously, the generated response bodies for the `HttpException` class and other exceptions derived from it (e.g., `BadRequestException` or `NotFoundException`) were inconsistent. In the latest major release, these exception responses will follow the same structure.
@@ -127,7 +285,7 @@ If you prefer the previous approach, you can restore it by setting the `exceptio
127285
128286
```typescript
129287
new ValidationPipe({
130-
exceptionFactory: errors => new BadRequestException(errors),
288+
exceptionFactory: (errors) => new BadRequestException(errors),
131289
});
132290
```
133291

‎content/pipes.md

Lines changed: 1 addition & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -445,97 +445,5 @@ We leave the implementation of this pipe to the reader, but note that like all o
445445

446446
#### The built-in ValidationPipe
447447

448-
Fortunately, you don't have to build these pipes on your own since the `ValidationPipe` and the `ParseIntPipe` are provided by Nest out-of-the-box. (Keep in mind that `ValidationPipe` requires both `class-validator` and `class-transformer` packages to be installed).
448+
Fortunately, you don't have to build these pipes on your own since the `ValidationPipe` (along with `ParseIntPipe`, `ParseBoolPipe`, `ParseArrayPipe` and `ParseUUIDPipe`) are provided by Nest out-of-the-box. The built-in `ValidationPipe` offers more options than in the sample we built in this chapter, which has been kept basic for the sake of illustrating the basic mechanics of a pipe. You can find full details, along with lots of examples [here](/techniques/validation).
449449

450-
The built-in `ValidationPipe` offers more options than in the sample we built in this chapter, which has been kept basic for the sake of illustrating the basic mechanics of a pipe. You can find lots of examples [here](/techniques/validation).
451-
452-
One such option is `transform`. Recall the earlier discussion about deserialized body objects being vanilla JavaScript objects (i.e., not having our DTO type). So far, we've used the pipe to validate our payload. You may recall that in the process, we used `class-transform` to temporarily convert our plain object into a typed object so that we could do the validation. The built-in ValidationPipe can also, optionally, return this converted object. We enable this behavior by passing in a configuration object to the pipe. For this option, pass a config object with the field `transform` with a value `true` as shown below:
453-
454-
```typescript
455-
@@filename(cats.controller)
456-
@Post()
457-
@UsePipes(new ValidationPipe({ transform: true }))
458-
async create(@Body() createCatDto: CreateCatDto) {
459-
this.catsService.create(createCatDto);
460-
}
461-
```
462-
463-
> info **Hint** The `ValidationPipe` is imported from the `@nestjs/common` package.
464-
465-
Because this pipe is based on the `class-validator` and `class-transformer` libraries, there are many additional options available. Like the `transform` option above, you configure these settings via a configuration object passed to the pipe. Following are the built-in options:
466-
467-
```typescript
468-
export interface ValidationPipeOptions extends ValidatorOptions {
469-
transform?: boolean;
470-
disableErrorMessages?: boolean;
471-
exceptionFactory?: (errors: ValidationError[]) => any;
472-
}
473-
```
474-
475-
In addition to these, all `class-validator` options (inherited from the `ValidatorOptions` interface) are available:
476-
477-
<table>
478-
<tr>
479-
<th>Option</th>
480-
<th>Type</th>
481-
<th>Description</th>
482-
</tr>
483-
<tr>
484-
<td><code>skipMissingProperties</code></td>
485-
<td><code>boolean</code></td>
486-
<td>If set to true, validator will skip validation of all properties that are missing in the validating object.</td>
487-
</tr>
488-
<tr>
489-
<td><code>whitelist</code></td>
490-
<td><code>boolean</code></td>
491-
<td>If set to true, validator will strip validated (returned) object of any properties that do not use any validation decorators.</td>
492-
</tr>
493-
<tr>
494-
<td><code>forbidNonWhitelisted</code></td>
495-
<td><code>boolean</code></td>
496-
<td>If set to true, instead of stripping non-whitelisted properties validator will throw an exception.</td>
497-
</tr>
498-
<tr>
499-
<td><code>forbidUnknownValues</code></td>
500-
<td><code>boolean</code></td>
501-
<td>If set to true, attempts to validate unknown objects fail immediately.</td>
502-
</tr>
503-
<tr>
504-
<td><code>disableErrorMessages</code></td>
505-
<td><code>boolean</code></td>
506-
<td>If set to true, validation errors will not be returned to the client.</td>
507-
</tr>
508-
<tr>
509-
<td><code>errorHttpStatusCode</code></td>
510-
<td><code>number</code></td>
511-
<td>This setting allows you to specify which exception type will be used in case of an error. By default it throws <code>BadRequestException</code>.</td>
512-
</tr>
513-
<tr>
514-
<td><code>exceptionFactory</code></td>
515-
<td><code>Function</code></td>
516-
<td>Takes an array of the validation errors and returns an exception object to be thrown.</td>
517-
</tr>
518-
<tr>
519-
<td><code>groups</code></td>
520-
<td><code>string[]</code></td>
521-
<td>Groups to be used during validation of the object.</td>
522-
</tr>
523-
<tr>
524-
<td><code>dismissDefaultMessages</code></td>
525-
<td><code>boolean</code></td>
526-
<td>If set to true, the validation will not use default messages. Error message always will be <code>undefined</code> if
527-
its not explicitly set.</td>
528-
</tr>
529-
<tr>
530-
<td><code>validationError.target</code></td>
531-
<td><code>boolean</code></td>
532-
<td>Indicates if target should be exposed in <code>ValidationError</code></td>
533-
</tr>
534-
<tr>
535-
<td><code>validationError.value</code></td>
536-
<td><code>boolean</code></td>
537-
<td>Indicates if validated value should be exposed in <code>ValidationError</code>.</td>
538-
</tr>
539-
</table>
540-
541-
> info **Notice** Find more information about the `class-validator` package in its [repository](https://github.com/typestack/class-validator).

0 commit comments

Comments
 (0)