GraphQL subscriptions enable you to subscribe to events under a source stream and receive notifications in real time via a response stream when a selected event executes.

Once a GraphQL subscription is executed, a persistent function is created on the server that maps an underlying source stream to a returned response stream.

GraphQL subscriptions differ from queries in the way the data is delivered to the client.

Queries immediately returns a single response, while subscriptions return a result every time data is published on a topic the client has subscribed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import { GraphQLServer, PubSub } from 'graphql-yoga'

const typeDefs = `
  type Query {
    hello: String!
  }

  type Counter {
    count: Int!
    countStr: String
  }

  type Subscription {
    counter: Counter!
  }
`

const resolvers = {
  Query: {
    hello: () => `Hello`,
  },
  Counter: {
    countStr: counter => `Current count: ${counter.count}`,
  },
  Subscription: {
    counter: {
      subscribe: (parent, args, { pubsub }) => {
        const channel = Math.random().toString(36).substring(2, 15) // random channel name
        let count = 0
        setInterval(() => pubsub.publish(channel, { counter: { count: count++ } }), 2000)
        return pubsub.asyncIterator(channel)
      },
    }
  },
}

Now, let’s create a simple PubSub instance - it is a simple pubsub implementation, based on EventEmitter. Alternative EventEmitter implementations can be passed by an options object to the PubSub constructor.

1
const pubsub = new PubSub()

To understand the fundamental of Subscriptions is convenient to know these three technologies:

1. EventEmitter.
   • Review the chapter on EventEmitters.
   • If you want to practice more with the event emitters you can optionally do the lab networking.

2. Another concept that you have to know before going to GraphQL subscriptions is Async Generators. If you don’t feel confident about async generators, review these lessons:

   • Chapter Async iteration and generators of JavaScript.info (see also the repo https://github.com/ULL-MII-SYTWS-2021/learning-async-iteration-and-generators)
   • Chapter Iterables of JavaScript.info
   • Chapter Generators of JavaScript.info
   • And then optionally do the lab Async Generators: First Come First Served For Await to know more about async generators.
3. The third technoloy that it is convenient for you to know is websockets. You can optionally do the lab Websockets

Before to continue with the rest of the code let us review the

• EventEmitter class

1
const server = new GraphQLServer({ typeDefs, resolvers, context: { pubsub } })

pubsub is a class that exposes a simple publish and subscribe API.

It sits between your application’s logic and the GraphQL subscriptions engine - it receives a publish command from your app logic and pushes it to your GraphQL execution engine.

graphql-subscriptions exposes a default PubSub class you can use for a simple usage of data publication.

The PubSub implementation also includes a mechanism that converts a specific PubSub event into a stream of AsyncIterator, which you can use with graphql subscriptions resolver.

1
server.start(() => console.log('Server is running on localhost:4000'))

Now when we visit localhost:4000 and subscribe we can see the counters moving:

References

• See folder subscriptions/hello/ in the repo crguezl/graphql-yoga-examples`