Subscriptions

The shelter's front desk shows new arrivals as they come in, and the adoption team's screen should announce every adoption the moment it happens. Polling, asking every few seconds whether anything changed, is wasteful when nothing did and late when something did. GraphQL's third operation type is the subscription: the client subscribes once, the connection stays open, and the server pushes a result each time the event happens. Each result is shaped by the subscription's selection, like a query's answer.

How events flow

A subscription resolver returns an async iterator, a stream of events. Mutations publish to it. graphql-subscriptions provides the glue, PubSub: publish(trigger, payload) sends a payload to everyone iterating over asyncIterableIterator(trigger). The docs create one module-level PubSub. Providing it under a token instead gives every class the same instance through injection, and lets tests or production swap it for one backed by Redis:

export const EVENTS = 'EVENTS';
export const eventsProvider: Provider = { provide: EVENTS, useValue: new PubSub() };

constructor(@Inject(EVENTS) private readonly events: PubSub) {}

The in-memory PubSub works inside one process only. With several servers behind a load balancer, a mutation on one never reaches subscribers on another, which is why production uses a shared implementation.

The subscription

@Mutation(() => Shift)
bookShift(@Args('input') input: ShiftInput): Shift {
  const shift = this.shifts.book(input);
  this.events.publish('shiftBooked', { shiftBooked: shift });
  return shift;
}

@Subscription(() => Shift)
shiftBooked() {
  return this.events.asyncIterableIterator('shiftBooked');
}

The payload is published under the subscription's name, { shiftBooked: shift }, because GraphQL resolves the subscription field from it like any other object. Publish the shift itself and every subscriber receives Cannot return null for non-nullable field Subscription.shiftBooked. A subscription method that forgets to return its iterator gives GraphQL nothing to iterate, and subscribing fails.

Two options shape what each subscriber receives:

• filter(payload, variables) runs for each subscriber and each event, and delivers the event only when it returns true. variables are the subscription's own arguments, so shiftBooked(day: "MON") can receive Mondays only. Declare the argument with @Args() on the method, or GraphQL refuses it.
• resolve(payload) turns the published payload into the value of the field. With it, publish whatever is convenient, { shift, by } for instance, and return the field's value directly, not wrapped in the subscription's name.

Over the wire, and in tests

In production subscriptions travel over WebSockets: subscriptions: { 'graphql-ws': true } in forRoot() opens a socket server beside the HTTP endpoint, and clients such as GraphiQL or Apollo Client connect to it. This runtime has no socket server, so this lesson is graded the way the docs suggest testing a schema without one: the specs take the schema from app.get(GraphQLSchemaHost) and call graphql's own subscribe() and execute(). subscribe() returns the same async iterator a socket server would read, and each next() resolves with the next result. The resolvers, filters and PubSub are the same code either way.

Your task

test/cats.subscriptions.spec.ts is the contract; read it first. CatsService can add a cat and find one.

1. Provide a PubSub under the token PUB_SUB in CatsModule, and inject it into the resolver.
2. addCat publishes the new cat to the catAdded subscription, and adoptCat publishes the cat and the adopter.
3. A catAdded(breed: String) subscription returns every new cat, or only those of breed when a subscriber gives one.
4. A catAdopted subscription returns a String: <name> went home with <adopter>. An adoption the service refuses publishes nothing.

When it fails

• Cannot return null for non-nullable field Subscription.catAdded.: the payload was published without the subscription's name as its key.
• Cannot read properties of undefined (reading 'breed') in the filter: the filter expects { catAdded } and the payload is something else.
• The Siamese subscriber also receives the Tabby: no filter, or it ignores variables.
• catAdopted fails with an object where a String was expected: without resolve, GraphQL reads catAdopted from the payload and finds nothing.

Remember

• A subscription returns an async iterator; mutations publish to it through PubSub.
• Publish { subscriptionName: value }, or give the subscription a resolve.
• filter(payload, variables) decides per subscriber; variables are the subscription's arguments.
• WebSockets carry subscriptions in production; the schema itself can run them in tests.