Merge pull request #1121 from nestjs/feat/mapped-types-generator

feat(): add mapped types, inheritance, generator

Author: kamilmysliwiec

content/graphql/cli-plugin.md

@@ -0,0 +1,111 @@
+### CLI Plugin
+
+> warning **Warning** This chapter applies only to the code first approach.
+
+TypeScript's metadata reflection system has several limitations which make it impossible to, for instance, determine what properties a class consists of or recognize whether a given property is optional or required. However, some of these constraints can be addressed at compilation time. Nest provides a plugin that enhances the TypeScript compilation process to reduce the amount of boilerplate code required.
+
+> info **Hint** This plugin is **opt-in**. If you prefer, you can declare all decorators manually, or only specific decorators where you need them.
+
+#### Overview
+
+The GraphQL plugin will automatically:
+
+- annotate all input object, object type and args classes properties with `@Field` unless `@HideField` is used
+- set the `nullable` property depending on the question mark (e.g. `name?: string` will set `nullable: true`)
+- set the `type` property depending on the type (supports arrays as well)
+
+Please, note that your filenames **must have** one of the following suffixes in order to be analyzed by the plugin: `['.input.ts', '.args.ts', '.entity.ts', '.model.ts']` (e.g., `author.entity.ts`). If you are using a different suffix, you can adjust the plugin's behavior by specifying the `typeFileNameSuffix` option (see below).
+
+With what we've learned so far, you have to duplicate a lot of code to let the package know how your type should be declared in GraphQL. For example, you could define a simple `Author` class as follows:
+
+```typescript
+@@filename(authors/models/author.model)
+@ObjectType()
+export class Author {
+  @Field(type => Int)
+  id: number;
+
+  @Field({ nullable: true })
+  firstName?: string;
+
+  @Field({ nullable: true })
+  lastName?: string;
+
+  @Field(type => [Post])
+  posts: Post[];
+}
+```
+
+While not a significant issue with medium-sized projects, it becomes verbose & hard to maintain once you have a large set of classes.
+
+By enabling the GraphQL plugin, the above class definition can be declared simply:
+
+```typescript
+@@filename(authors/models/author.model)
+@ObjectType()
+export class Author {
+  @Field(type => Int)
+  id: number;
+  firstName?: string;
+  lastName?: string;
+  posts: Post[];
+}
+```
+
+The plugin adds appropriate decorators on-the-fly based on the **Abstract Syntax Tree**. Thus, you won't have to struggle with `@Field` decorators scattered throughout the code.
+
+> info **Hint** The plugin will automatically generate any missing swagger properties, but if you need to override them, simply set them explicitly via `@Field()`.
+#### Using the CLI plugin
+To enable the plugin, open `nest-cli.json` (if you use [Nest CLI](/cli/overview)) and add the following `plugins` configuration:
+
+```javascript
+{
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "plugins": ["@nestjs/graphql/plugin"]
+  }
+}
+```
+
+You can use the `options` property to customize the behavior of the plugin.
+
+```javascript
+"plugins": [
+  {
+    "name": "@nestjs/graphql/plugin",
+    "options": {
+      "typeFileNameSuffix": [".input.ts", ".args.ts"]
+    }
+  }
+]
+```
+
+The `options` property has to fulfill the following interface:
+
+```typescript
+export interface PluginOptions {
+  typeFileNameSuffix?: string[];
+}
+```
+
+<table>
+  <tr>
+    <th>Option</th>
+    <th>Default</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>typeFileNameSuffix</code></td>
+    <td><code>['.input.ts', '.args.ts', '.entity.ts', '.model.ts']</code></td>
+    <td>GraphQL types files suffix</td>
+  </tr>
+</table>
+
+If you don't use the CLI but instead have a custom `webpack` configuration, you can use this plugin in combination with `ts-loader`:
+
+```javascript
+getCustomTransformers: (program: any) => ({
+  before: [require('@nestjs/graphql/plugin').before({}, program)]
+}),
+```

content/graphql/mapped-types.md

@@ -0,0 +1,108 @@
+### Mapped types
+
+> warning **Warning** This chapter applies only to the code first approach.
+
+As you build out features like CRUD (Create/Read/Update/Delete) it's often useful to construct variants on a base entity type. Nest provides several utility functions that perform type transformations to make this task more convenient.
+
+#### Partial
+
+When building input validation types (also called DTOs), it's often useful to build **create** and **update** variations on the same type. For example, the **create** variant may require all fields, while the **update** variant may make all fields optional.
+
+Nest provides the `PartialType()` utility function to make this task easier and minimize boilerplate.
+
+The `PartialType()` function returns a type (class) with all the properties of the input type set to optional. For example, suppose we have a **create** type as follows:
+
+```typescript
+@InputType()
+class CreateUserInput {
+  @Field()
+  email: string;
+
+  @Field()
+  password: string;
+
+  @Field()
+  firstName: string;
+}
+```
+
+By default, all of these fields are required. To create a type with the same fields, but with each one optional, use `PartialType()` passing the class reference (`CreateUserInput`) as an argument:
+
+```typescript
+@InputType()
+export class UpdateUserInput extends PartialType(CreateUserInput) {}
+```
+
+> info **Hint** The `PartialType()` function is imported from the `@nestjs/graphql` package.
+
+The `PartialType()` function takes an optional second argument that is a reference to the decorator factory of the type being extended. In the example above, we are extending `CreateUserInput` which is annotated with the `@InputType()` decorator. We didn't need to pass `InputType` as the second argument since it's the default value. If you want to extend a class decorated with `@ObjectType`, pass `ObjectType` as the second argument. For example:
+
+```typescript
+@InputType()
+export class UpdateUserInput extends PartialType(User, ObjectType) {}
+```
+
+#### Pick
+
+The `PickType()` function constructs a new type (class) by picking a set of properties from an input type. For example, suppose we start with a type like:
+
+```typescript
+@InputType()
+class CreateUserInput {
+  @Field()
+  email: string;
+
+  @Field()
+  password: string;
+
+  @Field()
+  firstName: string;
+}
+```
+
+We can pick a set of properties from this class using the `PickType()` utility function:
+
+```typescript
+@InputType()
+export class UpdateEmailInput extends PickType(CreateUserInput, ['email']) {}
+```
+
+> info **Hint** The `PickType()` function is imported from the `@nestjs/graphql` package.
+
+#### Omit
+
+The `OmitType()` function constructs a type by picking all properties from an input type and then removing a particular set of keys. For example, suppose we start with a type like:
+
+```typescript
+@InputType()
+class CreateUserInput {
+  @Field()
+  email: string;
+
+  @Field()
+  password: string;
+
+  @Field()
+  firstName: string;
+}
+```
+
+We can generate a derived type that has every property **except** `email` as shown below. In this construct, the second argument to `OmitType` is an array of property names.
+
+```typescript
+@InputType()
+export class UpdateUserInput extends OmitType(CreateUserInput, ['email']) {}
+```
+
+> info **Hint** The `OmitType()` function is imported from the `@nestjs/graphql` package.
+
+#### Composition
+
+The type mapping utility functions are composable. For example, the following will produce a type (class) that has all of the properties of the `CreateUserInput` type except for `email`, and those properties will be set to optional:
+
+```typescript
+@InputType()
+export class UpdateUserInput extends PartialType(
+  OmitType(CreateUserInput, ['email']),
+) {}
+```

content/graphql/mutations.md

@@ -39,7 +39,7 @@ export class UpvotePostInput {
 }
 ```
 
-> info **Hint** The `@InputType()` decorator takes an options object as an argument, so you can, for example, specify the input type's description. Note that, due to TypeScript's metadata reflection system limitations, you must either use the `@Field` decorator to manually indicate a type, or use a [CLI plugin](/graphql/resolvers#cli-plugin).
+> info **Hint** The `@InputType()` decorator takes an options object as an argument, so you can, for example, specify the input type's description. Note that, due to TypeScript's metadata reflection system limitations, you must either use the `@Field` decorator to manually indicate a type, or use a [CLI plugin](/graphql/cli-plugin).
 
 We can then use this type in the resolver class:
 

content/graphql/quick-start.md

@@ -171,6 +171,18 @@ definitionsFactory.generate({
 
 A fully working schema first sample is available [here](https://github.com/nestjs/nest/tree/master/sample/12-graphql-schema-first).
 
+#### Accessing generated schema
+
+In some circumstances (for example end-to-end tests), you may want to get a reference to the generated schema object. In end-to-end tests, you can then run queries using the `graphql` object without using any HTTP listeners.
+
+You can access the generated schema (in either the code first or schema first approach), using the `GraphQLSchemaHost` class:
+
+```typescript
+const { schema } = app.get(GraphQLSchemaHost);
+```
+
+> info **Hint** You must call the `GraphQLSchemaHost#schema` getter after the application has been initialized (after the `onModuleInit` hook has been triggered by either the `app.listen()` or `app.init()` method).
+
 #### Async configuration
 
 When you need to pass module options asynchronously instead of statically, use the `forRootAsync()` method. As with most dynamic modules, Nest provides several techniques to deal with async configuration.