Unions

Union type khá giống interface, nhưng chúng không được phép chỉ định bất kỳ field chung nào giữa các type (đọc thêm tại đây). Union hữu ích khi bạn cần trả về các kiểu dữ liệu rời rạc (disjoint) từ một field duy nhất.

Code first

Để định nghĩa một GraphQL union type, chúng ta phải định nghĩa các class mà union này sẽ được cấu thành từ đó. Theo ví dụ từ tài liệu Apollo, chúng ta sẽ tạo hai class. Đầu tiên, Book:

import { Field, ObjectType } from '@nestjs/graphql';

@ObjectType()
export class Book {
  @Field()
  title: string;
}

Và sau đó Author:

import { Field, ObjectType } from '@nestjs/graphql';

@ObjectType()
export class Author {
  @Field()
  name: string;
}

Với hai class này, đăng ký union ResultUnion bằng hàm createUnionType export từ package @nestjs/graphql:

export const ResultUnion = createUnionType({
  name: 'ResultUnion',
  types: () => [Author, Book] as const,
});

Bây giờ, chúng ta có thể tham chiếu ResultUnion trong query:

@Query(() => [ResultUnion])
search(): Array<typeof ResultUnion> {
  return [new Author(), new Book()];
}

Kết quả sẽ sinh ra phần schema GraphQL sau ở dạng SDL:

type Author {
  name: String!
}

type Book {
  title: String!
}

union ResultUnion = Author | Book

type Query {
  search: [ResultUnion!]!
}

Function resolveType() mặc định do thư viện sinh ra sẽ xác định type dựa trên giá trị trả về từ phương thức resolver. Điều đó có nghĩa là việc trả về instance của class thay vì literal JavaScript object là bắt buộc.

Để cung cấp một function resolveType() tùy chỉnh, truyền thuộc tính resolveType vào object options của hàm createUnionType(), như sau:

export const ResultUnion = createUnionType({
  name: 'ResultUnion',
  types: () => [Author, Book] as const,
  resolveType(value) {
    if (value.name) {
      return Author;
    }
    if (value.title) {
      return Book;
    }
    return null;
  },
});

Schema first

Để định nghĩa một union trong cách tiếp cận schema first, chỉ cần tạo một GraphQL union bằng SDL.

type Author {
  name: String!
}

type Book {
  title: String!
}

union ResultUnion = Author | Book

Sau đó, bạn có thể dùng tính năng sinh typing (như đã trình bày ở chương quick start) để sinh ra định nghĩa TypeScript tương ứng:

export class Author {
  name: string;
}

export class Book {
  title: string;
}

export type ResultUnion = Author | Book;

Union yêu cầu thêm một field __resolveType trong resolver map để xác định union nên resolve về type nào. Ngoài ra, lưu ý rằng class ResultUnionResolver phải được đăng ký như một provider trong một module bất kỳ. Hãy tạo một class ResultUnionResolver và định nghĩa phương thức __resolveType.

@Resolver('ResultUnion')
export class ResultUnionResolver {
  @ResolveField()
  __resolveType(value) {
    if (value.name) {
      return 'Author';
    }
    if (value.title) {
      return 'Book';
    }
    return null;
  }
}

Enums

Enumeration type là một kiểu scalar đặc biệt bị giới hạn trong một tập giá trị được phép cụ thể (đọc thêm tại đây). Điều này cho phép bạn:

• kiểm tra rằng bất kỳ argument nào thuộc type này đều nằm trong các giá trị được phép
• truyền đạt qua hệ thống type rằng một field sẽ luôn là một trong số hữu hạn giá trị

Code first

Khi dùng cách tiếp cận code first, bạn định nghĩa một GraphQL enum type bằng cách đơn giản là tạo một TypeScript enum.

export enum AllowedColor {
  RED,
  GREEN,
  BLUE,
}

Với enum này, đăng ký AllowedColor bằng hàm registerEnumType export từ package @nestjs/graphql:

registerEnumType(AllowedColor, {
  name: 'AllowedColor',
});

Bây giờ bạn có thể tham chiếu AllowedColor trong các type của mình:

@Field(type => AllowedColor)
favoriteColor: AllowedColor;

Kết quả sẽ sinh ra phần schema GraphQL sau ở dạng SDL:

enum AllowedColor {
  RED
  GREEN
  BLUE
}

Để cung cấp mô tả cho enum, truyền thuộc tính description vào hàm registerEnumType().

registerEnumType(AllowedColor, {
  name: 'AllowedColor',
  description: 'The supported colors.',
});

Để cung cấp mô tả cho từng giá trị của enum, hoặc để đánh dấu một giá trị là deprecated, truyền thuộc tính valuesMap, như sau:

registerEnumType(AllowedColor, {
  name: 'AllowedColor',
  description: 'The supported colors.',
  valuesMap: {
    RED: {
      description: 'The default color.',
    },
    BLUE: {
      deprecationReason: 'Too blue.',
    },
  },
});

Điều này sẽ sinh ra schema GraphQL sau ở dạng SDL:

"""
The supported colors.
"""
enum AllowedColor {
  """
  The default color.
  """
  RED
  GREEN
  BLUE @deprecated(reason: "Too blue.")
}

Schema first

Để định nghĩa một enumerator trong cách tiếp cận schema first, chỉ cần tạo một GraphQL enum bằng SDL.

enum AllowedColor {
  RED
  GREEN
  BLUE
}

Sau đó bạn có thể dùng tính năng sinh typing (như đã trình bày ở chương quick start) để sinh ra định nghĩa TypeScript tương ứng:

export enum AllowedColor {
  RED
  GREEN
  BLUE
}

Đôi khi backend cần dùng một giá trị nội bộ khác cho enum so với giá trị công khai trong API. Trong ví dụ này, API chứa RED, nhưng trong resolver ta có thể dùng #f00 thay vào đó (đọc thêm tại đây). Để làm được điều này, khai báo một resolver object cho enum AllowedColor:

export const allowedColorResolver: Record<keyof typeof AllowedColor, any> = {
  RED: '#f00',
};

Sau đó dùng resolver object này cùng với thuộc tính resolvers của phương thức GraphQLModule#forRoot(), như sau:

GraphQLModule.forRoot({
  resolvers: {
    AllowedColor: allowedColorResolver,
  },
});