Chapter 14

GraphQL Server Setup

Step 1: Install Dependencies

npm install @apollo/server @nestjs/apollo @nestjs/graphql graphql ts-morph

@apollo/server: This package is part of the Apollo GraphQL ecosystem and provides a GraphQL server implementation. It allows you to create a GraphQL server using Node.js, enabling you to define your GraphQL schema, and resolvers, and handle incoming GraphQL queries and mutations.

@nestjs/apollo: This package is an integration package provided by the NestJS framework. It allows you to use Apollo Server seamlessly within a NestJS application. NestJS is a powerful Node.js framework that provides a modular and structured approach to building scalable and maintainable server-side applications.

@nestjs/graphql: This package is another part of the NestJS ecosystem and provides GraphQL support for NestJS applications. It allows you to define GraphQL schemas, and resolvers, and use decorators to annotate your classes and methods to create GraphQL endpoints. It works in conjunction with @apollo/server or other GraphQL server implementations.

graphql: This package is the core GraphQL library that provides the fundamental building blocks for working with GraphQL. It includes utilities for parsing, validating, and executing GraphQL queries and mutations. It is a widely used package in the GraphQL community and is required by most GraphQL server implementations.

ts-morph: This package is a TypeScript AST (Abstract Syntax Tree) manipulation library. It allows you to programmatically analyze, modify, and generate TypeScript code. It can be particularly useful when working with code generation or refactoring tools, such as generating TypeScript types from GraphQL schemas or modifying existing TypeScript files programmatically.

In summary, the packages we mentioned are commonly used in the context of building GraphQL servers with NestJS and Apollo. They provide the necessary tools and integrations to define GraphQL schemas, handle incoming queries and mutations, and manipulate TypeScript code when needed.

Step 2: Import GraphQL Module

GraphQLModule.forRoot<ApolloDriverConfig>({

      driver: ApolloDriver,

      typePaths: ['./**/*.graphql'],

      definitions: {

        path: join(process.cwd(), 'src/graphql.ts'),

        outputAs: 'class',

      },

    }),

Step 3: Create a Schema File

A schema file named song.graphql must be created within the songs directory. This file defines the GraphQL schema, outlining the types, queries, mutations, and subscriptions for song-related operations, serving as a blueprint for the GraphQL API structure. It is considered good practice to maintain schema files within their respective domain folders to encapsulate and modularize the API definitions, facilitating better maintainability and scalability of the application's GraphQL architecture.

type Song {

  id: ID!

  title: String!

}

type Query {

  songs: [Song!]!

}

Utilizing this schema, one can execute GraphQL queries to retrieve data regarding songs. The sole query operation provided is songs, yielding an array of song objects, with each object including properties such as ID and title.

Best practices recommend ensuring that each query is optimized for performance, possibly by leveraging indexes on the ID field to expedite lookup times. Additionally, implementing proper error handling and security measures, such as validation and authentication on queries, can protect against inefficient data retrieval and unauthorized access.

For example, to retrieve all the songs, you can execute the following GraphQL query:

query {

  songs {

    id

    title

  }

}

The query retrieves all songs from the GraphQL server, delivering both IDs and titles to the client.

For the query to function in a production environment, resolvers must be developed to establish the methods of data retrieval upon execution of the songs query, which is not depicted in this schema outline.

Best practices suggest the implementation of resolvers should be designed to be efficient and scalable, often including pagination and filtering capabilities to handle large datasets. Additionally, implementing caching mechanisms can significantly enhance performance by reducing redundant database calls for frequently requested data.

Step 4: Generate Typings

When setting up a NestJS project, a generate-typings.ts file must be created in the root directory. This file is instrumental in generating TypeScript typings that align with the data models and provides strong typing benefits throughout the application.

A best practice in this process involves ensuring that the script within generate-typings.ts is both maintained with the current project's structure and executed as part of the build process. This maintains type accuracy, aiding in early detection of potential type mismatches or errors during development.

import { GraphQLDefinitionsFactory } from "@nestjs/graphql";

import { join } from "path";

const definitionsFactory = new GraphQLDefinitionsFactory();

definitionsFactory.generate({

  typePaths: ["./src/**/*.graphql"],

  path: join(process.cwd(), "src/graphql.ts"),

  outputAs: "class",

});

export class Song {

  id: string;

  title: string;

}

export abstract class IQuery {

  abstract songs():

    | Nullable<Nullable<Song>[]>

    | Promise<Nullable<Nullable<Song>[]>>;

}

type Nullable<T> = T | null;

In the context of Nest.js, when defining a resolver for GraphQL, specific types must be declared to ensure the proper resolution of queries and mutations. It is essential to accurately define the types to map the application's data structures to the GraphQL schema, facilitating clear and type-safe data exchange.

A best practice includes leveraging TypeScript's strong typing system within Nest.js to reinforce the integrity of GraphQL resolvers. By doing so, one ensures that the code aligns with the defined schema, reducing the potential for runtime errors and improving maintainability.

Step 4: Create Script for the Typings

"generate:typings": "ts-node generate-typings.ts",

You have to add a script in the package.json file. You can run this command by executing this script

npm run generate:typings

Define Queries and Mutations

Step 1: Define a query for a single song

In the given GraphQL schema definition, a Query type is defined to facilitate fetching of specific Song data by its unique identifier, ensuring a structured and type-safe way of querying the data. This approach optimizes the data retrieval process by allowing precise and efficient querying for only the required song information.

type Query {

  song(id: ID!): Song!

}

In the context of a NestJS application, extending the GraphQL schema to include queries for specific items, such as songs, enhances the API's capabilities. Such an extension allows clients to retrieve a single song using its unique identifier, which optimizes data retrieval by fetching only the required item rather than the entire collection.

It is a widely accepted best practice to provide such granular query capabilities, as it can significantly improve the performance of the application by reducing the amount of data transferred over the network and the load on the server. Additionally, crafting precise and efficient queries is a hallmark of well-designed GraphQL services, allowing for flexible and optimized client-server interactions.

query {

  song(id: "123") {

    id

    title

  }

}

Step 2: Define Mutations

The provided GraphQL schema defines mutations, which are operations that modify data on the server. Specifically, it includes mutations for creating, updating, and deleting a song, with clearly defined input types and expected result types.

In the context of a NestJS application utilizing GraphQL, it is crucial to design mutations to be precise in their intent and to return types that provide meaningful feedback about the outcome of the operation, such as the number of affected records. Best practices include careful naming conventions for clarity and the use of non-nullable types (!) where appropriate to enforce the presence of return data, enhancing the robustness of the API. It's also advisable to validate input objects to maintain data integrity and to use custom scalars for complex data types when needed.

type Mutation {

  createSong(title: String!): Song!

  updateSong(id: ID!, updateSongInput: UpdateSongInput!): UpdateResult!

  deleteSong(id: ID!): DeleteResult!

}

type UpdateSongInput {

  title: String

}

type UpdateResult {

  affected: Int!

}

type DeleteResult {

  affected: Int!

}

In NestJS, mutations in the schema reflect the capability to alter data within the application, encapsulating operations such as creating, updating, and deleting records. These mutation operations are critical for maintaining dynamic data states within the application and directly correspond to CRUD (Create, Read, Update, Delete) operations that are fundamental to persistent storage management.

Employing the createSong, updateSong, and deleteSong mutations allows for granular control over the song records, with the operations returning types UpdateResult and DeleteResult that furnish insights into the result of these mutations. As a best practice, ensuring these mutations are well-tested and transactional can help maintain data integrity and provide rollback mechanisms in case of failures. This provides robustness to the data management layer of a NestJS application.

Step 3: Generate Typings

npm run generate:typings

Resolve Queries and Mutations

Step 1: Refactor type UpdateSongInput to input

In NestJS, when using GraphQL, the UpdateSongInput type is defined to specify the shape of data that can be used as input for mutations, particularly for updating songs in this context. This GraphQL input type is crucial for validating the structure of client-provided data before it is processed by the server.

As a standard procedure, generating typings through the npm run generate:typings command ensures that the GraphQL schema changes are reflected in the TypeScript types. This step helps to maintain type safety across the application, preventing runtime errors due to type mismatches and facilitating a robust development environment.

input UpdateSongInput {

  title: String

}

Make sure to generate the typings by running npm run generate:typings.

Step 2: Create Song Resolver

This has a GraphQL resolver in a NestJS application, which is a key component for defining how data is fetched. The SongResolver class is decorated with @Resolver(), indicating its role in handling GraphQL queries, specifically for fetching songs using a service.

It adheres to best practices by leveraging dependency injection to incorporate the SongService, ensuring that the resolver remains modular and testable. Utilizing async/await for the getSongs query method, it promises a smooth, non-blocking operation that aligns with the scalable and efficient nature of a well-structured NestJS application.

import { Query, Resolver } from "@nestjs/graphql";

import { Song } from "src/graphql";

import { SongService } from "./song.service";

@Resolver()

export class SongResolver {

  constructor(private readonly songService: SongService) {}

  @Query("songs")

  async getSongs(): Promise<Song[]> {

    return this.songService.getSongs();

  }

}

Step 3 Register the Song Resolver in the Song Module

providers: [SongService, SongResolver],

Step 4: Resolve Song By a given Id

The @Query decorator in a NestJS GraphQL resolver indicates a query operation that fetches data according to the defined schema, with 'song' being the specific query field. The getSong method utilizes dependency injection to access the songService and execute its getSong method, providing a promise that resolves with a Song entity, identified by the unique 'id' argument passed to it.

Implementing such methods following the Single Responsibility Principle ensures that each function performs a specific task, improving maintainability and testability. Including comprehensive error handling within service methods helps to gracefully manage exceptions, ensuring reliable application behavior.

@Query('song')

  async getSong(

    @Args('id')

    id: string,

  ): Promise<Song> {

    return this.songService.getSong(id);

  }

Resolver with Song Mutation

Step 1: Add CreateSongInput

The GraphQL schema definition below th outlines a mutation operation for creating a song, specifying the structure for client requests. This mutation, createSong, takes a non-nullable CreateSongInput object as an argument and returns a non-nullable Song object, enforcing a contract where both input and output are required.

Incorporating non-nullable fields in GraphQL schema design ensures robustness by explicitly defining required data, which prevents erroneous data entry and streamlines client-server communication. As a best practice, precise input types and return types should be defined, making the API predictable and the codebase maintainable, as well as facilitating smoother frontend development with clearer expectations.

createSong(createSongInput: CreateSongInput!): Song!

input CreateSongInput {

  title: String!

}

npm run generate:typings

Step 2: Resolver with createSong mutation

This is a GraphQL resolver for song creation. It illustrates the resolver pattern that is part of NestJS's GraphQL module. The SongResolver class contains a mutation operation, which is an essential part of GraphQL's data manipulation language, allowing clients to create new data entries, in this case, a new song.

Incorporating Data Transfer Objects (DTOs), as seen with CreateSongDTO, is a recommended practice for ensuring the integrity of the data being transferred between the client and server. This DTO pattern aids in validating incoming data for mutations, enforcing a clear contract for the expected structure of the data, which is especially critical in GraphQL where the schema defines the API's capabilities and constraints.

import { CreateSongDTO } from "./dto/create-song-dto";

export class SongResolver {

  @Mutation("createSong")

  async createSong(

    @Args("createSongInput")

    args: CreateSongDTO

  ): Promise<Song> {

    return this.songService.createSong(args);

  }

}

Step 3: Resolver with Update Song Mutation

In the context of a GraphQL API with NestJS, the @Mutation decorator indicates an operation that modifies server-side data and corresponds to a POST/PUT/PATCH request in a RESTful API. This particular mutation, updateSong, is designed to update an existing song resource when provided with an identifier and the new data to apply.

Best practices suggest that mutation operations should be explicit in their intent and tightly scoped to ensure maintainability and clear understanding of their impact. Furthermore, the use of DTOs (Data Transfer Objects) like UpdateSongDTO for encapsulating the update data is recommended to enforce validation and encapsulation, which helps to maintain the integrity of the data being sent to the server.

@Mutation('updateSong')

  async updateSong(

    @Args('updateSongInput')

    args: UpdateSongDTO,

    @Args('id')

    id: string,

  ): Promise<UpdateResult> {

    return this.songService.updateSong(id, args);

  }

Step 4: Resolver with Delete Song Mutation

The @Mutation decorator indicates that deleteSong is a mutation operation in the GraphQL API, which allows clients to perform write operations, in this case, deleting a song by its identifier.

For maintainability and adherence to best practices, the mutation is handled through a service, encapsulating business logic away from the controller layer. This separation of concerns ensures that the controller is kept lean, with the service being responsible for interfacing with the data access layer to execute the deletion operation.

@Mutation('deleteSong')

  async deleteSong(

    @Args('id')

    id: string,

  ): Promise<DeleteResult> {

    return this.songService.deleteSong(id);

  }

Error Handling

Error handling is a crucial aspect of developing resilient applications, and within the context of a NestJS GraphQL service, throwing an error from a resolver, such as getSongs in SongResolver, allows for graceful failure management. This approach can encapsulate business logic validation and operational faults, providing clear feedback to the client about what went wrong.

Incorporating error handling at the resolver level adheres to best practices by localizing error management and maintaining clean separation of concerns. Structured correctly, it can streamline debugging and maintenance, ensuring that the GraphQL API communicates effectively with clients and enhances the overall robustness of the service.

@Query('songs')

  async getSongs(): Promise<Song[]> {

    // return this.songService.getSongs();

    // throw new Error('Unable to fetch songs!');

    throw new GraphQLError('Unable to fetch the songs', {

      extensions: {

        code: 'INTERNAL_SERVER_ERROR',

      },

    });

  }

In practice, structured error handling is crucial as it aids client applications in deciphering the nature of errors. The inclusion of an error code within the extensions of GraphQLError allows for consistent error processing and can be used to trigger specific client-side behavior. It's recommended to handle errors gracefully and provide meaningful error messages to maintain a seamless user experience. Moreover, logging such errors in a manner that they can be monitored and analyzed can lead to improved system robustness and quicker resolution of underlying issues.

$7 bundle of my best NestJS + backend developer Courses.
More details coming soon.