API with NestJS #29. Real-time updates with GraphQL subscriptions

February 15, 2021

This entry is part 29 of 121 in the API with NestJS

So far, in this series, we’ve used GraphQL both to fetch and modify data. While this covers many real-life cases, modern applications often include situations in which users need immediate feedback when some event occurs.

One of the solutions suggested by the GraphQL team is polling. In this technique, the client periodically requests the API for changes. It is a straightforward approach and works out of the box without much code. Unfortunately, usually, updates can be unpredictable. Therefore, polling is often wasteful and introduces unnecessary traffic in our API.

To counter the above issue, with GraphQL, we have a concept of subscriptions. They act as a way for the clients to listen for events in real-time. The client informs the server that it cares about a set of events. When they trigger, the server is responsible for notifying the client. To achieve that, the server needs to declare the events that the client can listen to.

Under the hood, an active connection between the client and the server establishes. Thanks to that, we can push messages from the server to our users. Usually, subscriptions in GraphQL are implemented with WebSockets, although the official specification does not enforce that. There were some attempts in implementing subscriptions using Server-sent events, for example.

If you want to know how to use NestJS with WebSockets, check out API with NestJS #26. Real-time chat with WebSockets

Implementing subscriptions with NestJS

The very first step in implementing subscriptions is enabling them. To do so, we need to turn on the installSubscriptionHandlers property.

app.module.ts

import { Module } from '@nestjs/common';

import { ConfigModule, ConfigService } from '@nestjs/config';

import { GraphQLModule } from '@nestjs/graphql';

import { join } from 'path';

@Module({

imports: [

GraphQLModule.forRootAsync({

imports: [ConfigModule],

inject: [ConfigService],

useFactory: (

configService: ConfigService,

) => ({

playground: Boolean(configService.get('GRAPHQL_PLAYGROUND')),

autoSchemaFile: join(process.cwd(), 'src/schema.gql'),

installSubscriptionHandlers: true

})

}),

// ...

controllers: [],

providers: [],

})

export class AppModule {}

Creating an instance of a PubSub

The first concept that we need to grasp is the PubSub. Its job is to be a middleman between the logic of our application and the GraphQL subscriptions engine. It does that by exposing a simple publish and subscribe API.

Under the hood, NestJS uses Apollo, which is a widespread GraphQL implementation. A part of the Apollo architecture is the graphql-subscriptions library. It does contain a ready-to-use PubSub. Unfortunately, it is not meant to be used in production, though, as mentioned in the docs. It wouldn’t work with multiple instances of our NestJS server. Also, it does not scale beyond a few connections.

Among the suggested PubSub implementations, the most popular seems to be the graphql-redis-subscriptions library.

We’ve already used Redis in this series in API with NestJS #24. Cache with Redis. Running the app in a Node.js cluster. If you want to know how to set up Redis with docker, check it out.

When initializing a PubSub, let’s take the advice from Jay McDoniel, one of the NestJS library maintainers. It includes defining a global module with an instance of the PubSub.

pubSub.module.ts

import { ConfigModule, ConfigService } from '@nestjs/config';

import { RedisPubSub } from 'graphql-redis-subscriptions';

import { Global, Module } from '@nestjs/common';

export const PUB_SUB = 'PUB_SUB';

@Global()

@Module({

imports: [ConfigModule],

providers: [

{

provide: PUB_SUB,

useFactory: (

configService: ConfigService

) => new RedisPubSub({

connection: {

host: configService.get('REDIS_HOST'),

port: configService.get('REDIS_PORT'),

}

}),

inject: [ConfigService]

}

exports: [PUB_SUB],

})

export class PubSubModule {}

Global modules should be registered only once, preferably in the AppModule, our root module. Doing so makes them available everywhere.

Defining the subscription

In the twenty-seventh part of this series, we’ve defined the model of a post. This article aims to define a subscription that allows our users to listen to newly-created posts.

To define a subscription using the code-first approach, we need to use the @Subscription() decorator.

posts.resolver.ts

import { Resolver, Subscription } from '@nestjs/graphql';

import { Post } from './models/post.model';

import PostsService from './posts.service';

import { Inject } from '@nestjs/common';

import { RedisPubSub } from 'graphql-redis-subscriptions';

import { PUB_SUB } from '../pubSub/pubSub.module';

const POST_ADDED_EVENT = 'postAdded';

@Resolver(() => Post)

export class PostsResolver {

constructor(

private postsService: PostsService,

@Inject(PUB_SUB) private pubSub: RedisPubSub

) {}

@Subscription(() => Post)

postAdded() {

return this.pubSub.asyncIterator(POST_ADDED_EVENT);

}

// ...

}

Please note that the name of the event matches the postAdded method. If that’s not the case, we need to pass additional options to the @Subscription() decorator.

Above, we return the AsyncIterator every time a client requests a subscription. Thanks to that, every time we call pubSub.publish(POST_ADDED_EVENT), the clients who subscribed will receive the event.

posts.resolver.ts

import { Args, Context, Mutation, Resolver } from '@nestjs/graphql';

import { Post } from './models/post.model';

import PostsService from './posts.service';

import { CreatePostInput } from './inputs/post.input';

import { Inject, UseGuards } from '@nestjs/common';

import RequestWithUser from '../authentication/requestWithUser.interface';

import { GraphqlJwtAuthGuard } from '../authentication/graphql-jwt-auth.guard';

import { RedisPubSub } from 'graphql-redis-subscriptions';

import { PUB_SUB } from '../pubSub/pubSub.module';

const POST_ADDED_EVENT = 'postAdded';

@Resolver(() => Post)

export class PostsResolver {

constructor(

private postsService: PostsService,

@Inject(PUB_SUB) private pubSub: RedisPubSub

) {}

@Mutation(() => Post)

@UseGuards(GraphqlJwtAuthGuard)

async createPost(

@Args('input') createPostInput: CreatePostInput,

@Context() context: { req: RequestWithUser },

) {

const newPost = await this.postsService.createPost(createPostInput, context.req.user);

this.pubSub.publish(POST_ADDED_EVENT, { postAdded: newPost });

return newPost;

}

// ...

}

Thanks to doing that, our clients can subscribe to incoming posts. We can try that through the GraphQL playground:

Subscribing to post creation

Above, we can see that the subscription is active, and the client listens to incoming events. When the post gets created, it is visible in the interface right away.

Subscribing to post creation with a result

Filtering events

We can pass additional options to the @Subscribe() decorator. One of them is the filter function. It has the payload and the variables as its arguments. If it returns false, the event is filtered out and not returned to the clients.

@Subscription(() => Post, {

filter: (payload, variables) => {

return payload.postAdded.title === 'Hello world!';

}

})

postAdded() {

return this.pubSub.asyncIterator(POST_ADDED_EVENT);

}

Modifying the payload before sending

Another optional option of the @Subscribe() decorator is the resolve function. It can modify the payload before sending it to the client.

@Subscription(() => Post, {

resolve: (value) => {

return {

...value.postAdded,

title: `Title: ${value.postAdded.title}`

}

})

postAdded() {

return this.pubSub.asyncIterator(POST_ADDED_EVENT);

}

We can also access injected providers both in the resolve and filter functions. To do that, use the following:

@Subscription(() => Post, {

filter: function (this: PostsResolver, payload, variables) {

const postsService = this.postsService;

return true;

resolve: function (this: PostsResolver, value) {

const postsService = this.postsService;

return {

...value.postAdded,

title: `Title: ${value.postAdded.title}`

}

})

postAdded() {

return this.pubSub.asyncIterator(POST_ADDED_EVENT);

}

Summary

In this article, we’ve looked into how we can update our users with our application’s newest state. Although one of the solutions might be polling, it has its drawbacks. Therefore, we’ve implemented subscriptions that under the hood use WebSockets. Combined with the Redis-based PubSub, we can send events to our users in a performant way.

Series Navigation<< API with NestJS #28. Dealing in the N + 1 problem in GraphQLAPI with NestJS #30. Scalar types in GraphQL >>

9 Comments

Oldest

Newest Most Voted

Inline Feedbacks

View all comments

koike

3 years ago

Do you publish all the code??

Author

Marcin Wanago

Reply to koike

You can find all of the code in this repository
https://github.com/mwanago/nestjs-typescript

Reply to Marcin Wanago

thank you!!!!!1

Kurt

2 years ago

“GET query missing.” this error presents in playground

Reply to Kurt

playground: Boolean(configService.get(‘GRAPHQL_PLAYGROUND’));

this is causing that error.

not really an expert to this and can’t understand why but i just changed it to this:

playground: Boolean(configService.get(‘GRAPHQL_PLAYGROUND’, true));

It seems the value ‘GRAPHQL_PLAYGROUND’ from configService is not available for some reason.

MichaelYao

Can we do this kind of subscription in restful API?

Juliusz

1 year ago

Reply to MichaelYao

Yes, with websockets https://docs.nestjs.com/websockets/gateways.
In general, this GraphQL subscriptions are also using websockets under the hood.

Ken

I got this error.

ERROR [ResolversExplorerService] “PostsResolver” resolver is request or transient-scoped. Resolvers that register subscriptions with the “@Subscription()” decorator must be static (singleton).

How can i fix it?

Adil

Thanks for writing this. Well written. One question that I posted on Stackoveflow as well is:
How is GraphQL Subscription any different from NestJS Gateway?

Both use ws under the hood.

Your thoughts?

Stack Overflow Question: https://stackoverflow.com/q/76309004/2467760