O pacote Apollo fornece uma abordagem code-first para construir APIs GraphQL com decoradores para tipos, resolvers, queries e mutations.

Instalação

bun add @apollo/server graphql graphql-ws

Configuração

Registre o módulo GraphQL na sua aplicação:

import { Module } from "nestelia";
import { GraphQLModule } from "nestelia/apollo";

@Module({
  imports: [
    GraphQLModule.forRoot({
      playground: true,
    }),
    UserModule,
  ],
})
class AppModule {}

Definições de Tipos

Object Types

import { ObjectType, Field } from "nestelia/apollo";

@ObjectType()
class User {
  @Field()
  id: string;

  @Field()
  name: string;

  @Field({ nullable: true })
  email?: string;
}

Input Types

import { InputType, Field } from "nestelia/apollo";

@InputType()
class CreateUserInput {
  @Field()
  name: string;

  @Field()
  email: string;
}

Enums

Registre enums com registerEnumType e sempre passe uma factory de tipo explícita para @Field(). O TypeScript emite String ou Number como design:type para campos de enum, portanto o construtor de schema não consegue inferir o tipo do enum automaticamente.

import { registerEnumType } from "nestelia/apollo";

enum Role {
  ADMIN = "ADMIN",
  USER = "USER",
}

registerEnumType(Role, { name: "Role", description: "User role" });

@ObjectType()
class User {
  @Field()
  name: string;

  // Factory de tipo explícita necessária para campos de enum
  @Field(() => Role)
  role: Role;
}

Union Types

Use createUnionType para union types code-first. A função resolveType pode retornar uma string com o nome do tipo ou um construtor de classe.

import { createUnionType } from "nestelia/apollo";

@ObjectType()
class Cat {
  @Field()
  meow: string;
}

@ObjectType()
class Dog {
  @Field()
  bark: string;
}

const PetUnion = createUnionType({
  name: "PetUnion",
  types: () => [Cat, Dog] as const,
  resolveType(value) {
    return "meow" in value ? Cat : Dog;
  },
});

@ObjectType()
class Owner {
  @Field(() => PetUnion)
  pet: typeof PetUnion;
}

Custom Scalars

import { Scalar } from "nestelia/apollo";

@Scalar("DateTime")
class DateTimeScalar {
  description = "ISO 8601 date-time string";

  serialize(value: Date) {
    return value.toISOString();
  }

  parseValue(value: string) {
    return new Date(value);
  }
}

Scalars Integrados

Seis scalars prontos para uso estão incluídos — sem configuração adicional:

Scalar	Tipo GraphQL	Tipo JS	Descrição
GraphQLDateTime	DateTime	Date	String ISO 8601 ↔ JS Date
GraphQLJSON	JSON	any	Qualquer valor JSON
GraphQLURL	URL	string	String de URL validada
GraphQLBigInt	BigInt	bigint	Inteiro de 64 bits, serializado como string
GraphQLEmailAddress	EmailAddress	string	Endereço de e-mail validado
GraphQLUUID	UUID	string	UUID, normalizado para minúsculas

import { GraphQLDateTime, GraphQLEmailAddress, GraphQLJSON, GraphQLUUID } from "nestelia/apollo";

@ObjectType()
class User {
  @Field(() => GraphQLUUID)
  id!: string;

  @Field(() => GraphQLEmailAddress)
  email!: string;

  @Field(() => GraphQLDateTime)
  createdAt!: Date;

  @Field(() => GraphQLJSON, { nullable: true })
  metadata?: Record<string, unknown>;
}

Tipos de Args

@ArgsType() marca uma classe cujas propriedades @Field() são expandidas como argumentos individuais de nível superior no schema — sem objeto de input de wrapper. Use com @Args() (sem nome):

import { ArgsType, Field, Int } from "nestelia/apollo";

@ArgsType()
class BooksArgs {
  @Field(() => Int, { nullable: true, defaultValue: 0 })
  offset!: number;

  @Field(() => Int, { nullable: true, defaultValue: 20 })
  limit!: number;
}

@Resolver(() => Book)
class BooksResolver {
  @Query(() => [Book])
  books(@Args() args: BooksArgs): Book[] {
    return this.store.slice(args.offset, args.offset + args.limit);
  }
}

Paginação

Baseada em offset

Paginated(ItemType) cria uma resposta paginada com items, total, hasNextPage, hasPreviousPage:

import { Paginated, Int } from "nestelia/apollo";

@ObjectType()
class BooksPage extends Paginated(Book) {}

@Query(() => BooksPage)
books(@Args() args: BooksArgs): BooksPage {
  const items = this.store.slice(args.offset, args.offset + args.limit);
  return {
    items,
    total: this.store.length,
    hasNextPage: args.offset + args.limit < this.store.length,
    hasPreviousPage: args.offset > 0,
  };
}

Relay (baseada em cursor)

import { createEdgeType, createConnectionType, PageInfo } from "nestelia/apollo";

@ObjectType()
class BookEdge extends createEdgeType(Book) {}

@ObjectType()
class BookConnection extends createConnectionType(Book, BookEdge) {}

@Query(() => BookConnection)
booksConnection(@Args("first", { type: () => Int }) first: number): BookConnection {
  const edges = this.store.slice(0, first).map((book, i) => ({
    node: book,
    cursor: Buffer.from(String(i)).toString("base64"),
  }));
  return {
    edges,
    pageInfo: { hasNextPage: first < this.store.length, hasPreviousPage: false,
      startCursor: edges[0]?.cursor, endCursor: edges.at(-1)?.cursor },
    totalCount: this.store.length,
  };
}

Resolver

Defina resolvers GraphQL com o decorador @Resolver():

import { Resolver, Query, Mutation, Args } from "nestelia/apollo";
import { Injectable, Inject } from "nestelia";

@Resolver(() => User)
@Injectable()
class UserResolver {
  constructor(@Inject(UserService) private userService: UserService) {}

  @Query(() => [User])
  async users() {
    return this.userService.findAll();
  }

  @Query(() => User)
  async user(@Args("id") id: string) {
    return this.userService.findById(id);
  }

  @Mutation(() => User)
  async createUser(@Args("input") input: CreateUserInput) {
    return this.userService.create(input);
  }
}

Field Resolvers

Use @FieldResolver() (ou o alias @ResolveField()) para resolver campos aninhados:

import { Resolver, FieldResolver, Parent } from "nestelia/apollo";

@Resolver(() => Post)
class PostResolver {
  @FieldResolver()
  async author(@Parent() post: Post) {
    return this.userService.findById(post.authorId);
  }
}

Subscriptions

import { Resolver, Subscription } from "nestelia/apollo";

@Resolver(() => User)
class UserResolver {
  @Subscription(() => User)
  userCreated() {
    return pubsub.asyncIterator("USER_CREATED");
  }
}

Context e Info

import { Context, Info } from "nestelia/apollo";

@Query(() => User)
async me(@Context("user") user: User, @Info() info: GraphQLResolveInfo) {
  return user;
}

Upload de arquivos

Nestelia implementa a especificação GraphQL multipart request. Nenhum pacote adicional necessário — GraphQLUpload e UploadedFile são nativos.

Arquivo único

import { GraphQLUpload, type UploadedFile } from "nestelia/apollo";

@Mutation(() => UploadResult)
async uploadFile(
  @Args("file", { type: () => GraphQLUpload }) file: Promise<UploadedFile>,
): Promise<UploadResult> {
  const upload = await file;
  // upload.filename, upload.mimetype, upload.size, upload.stream
  return { filename: upload.filename, mimetype: upload.mimetype, size: upload.size };
}

Múltiplos arquivos

@Mutation(() => MultiUploadResult)
async uploadFiles(
  @Args("files", { type: () => [GraphQLUpload] }) files: Promise<UploadedFile>[],
): Promise<MultiUploadResult> {
  const uploads = await Promise.all(files);
  return {
    count: uploads.length,
    totalSize: uploads.reduce((sum, f) => sum + f.size, 0),
  };
}

Streaming para o disco

import { createWriteStream } from "node:fs";
import { Writable } from "node:stream";

@Mutation(() => UploadResult)
async uploadFile(
  @Args("file", { type: () => GraphQLUpload }) file: Promise<UploadedFile>,
): Promise<UploadResult> {
  const upload = await file;
  const dest = createWriteStream(`./uploads/${upload.filename}`);
  await upload.stream.pipeTo(Writable.toWeb(dest));
  return { filename: upload.filename, mimetype: upload.mimetype, size: upload.size };
}

Exemplo de requisição multipart

operations: {"query":"mutation($file:Upload!){uploadFile(file:$file){filename size}}","variables":{"file":null}}
map:        {"0":["variables.file"]}
0:          <binary file data>

Interface UploadedFile

Propriedade	Tipo	Descrição
filename	string	Nome original do arquivo
mimetype	string	Tipo MIME
size	number	Tamanho em bytes
stream	ReadableStream	Web Streams readable stream
blob()	Promise<Blob>	Ler como Blob
arrayBuffer()	Promise<ArrayBuffer>	Ler como ArrayBuffer
text()	Promise<string>	Ler como string

Limites de upload

Configure os limites pela opção upload em GraphQLModule.forRoot (ou forRootAsync):

GraphQLModule.forRoot({
  autoSchemaFile: true,
  upload: {
    maxFiles: 5,              // máx. arquivos por requisição (padrão: 10)
    maxFileSize: 10_485_760,  // 10 MB por arquivo
  },
})

Opção	Tipo	Padrão	Descrição
maxFiles	number	10	Número máximo de arquivos por requisição
maxFileSize	number	—	Tamanho máximo por arquivo em bytes. Sem limite se omitido

Guards em Resolvers

import { UseGuards } from "nestelia";

@Resolver(() => User)
class AdminResolver {
  @Query(() => [User])
  @UseGuards(AdminGuard)
  async allUsers() {
    return this.userService.findAll();
  }
}