Ably is a pub/sub messaging platform with a suite of integrated services to deliver complete realtime functionality directly to end-users. In the context of GraphQL, we can use it to publish when a mutation is fired and subscribe to the result through a subscription query.
This package implements the PubSubEngine Interface from the graphql-subscriptions package and also the new AsyncIterator interface. It allows you to connect your subscription manger to an Ably PubSub mechanism to support multiple subscription manager instances.
Check out the example folder for basic usage.
npm install graphql-ably-pubsub
or
yarn add graphql-ably-pubsub
Define your GraphQL schema with a Subscription
type:
schema {
query: Query
mutation: Mutation
subscription: Subscription
}
type Subscription {
somethingChanged: Result
}
type Result {
id: String
}
Now, let's create a simple AblyPubSub
instance:
import { AblyPubSub } from "graphql-ably-pubsub";
const pubsub = new AblyPubSub();
Now, implement your Subscriptions type resolver, using the pubsub.asyncIterator
to map the event you need:
const SOMETHING_CHANGED_TOPIC = "something_changed";
export const resolvers = {
Subscription: {
somethingChanged: {
subscribe: () => pubsub.asyncIterator(SOMETHING_CHANGED_TOPIC),
},
},
};
Subscriptions resolvers are not a function, but an object with
subscribe
method, that returnsAsyncIterable
.
Calling the method asyncIterator
of the AblyPubSub
instance will subscribe to the topic provided and will return an AsyncIterator
bound to the AblyPubSub instance and listens to any event published on that topic.
Now, the GraphQL engine knows that somethingChanged
is a subscription, and every time we will use pubsub.publish
over this topic, the AblyPubSub
will PUBLISH
the event to all other subscribed instances and those in their turn will emit the event to GraphQL using the next
callback given by the GraphQL engine.
pubsub.publish(SOMETHING_CHANGED_TOPIC, { somethingChanged: { id: "123" } });
export const resolvers = {
Subscription: {
somethingChanged: {
subscribe: (_, args) =>
pubsub.asyncIterator(`${SOMETHING_CHANGED_TOPIC}.${args.relevantId}`),
},
},
};
import { withFilter } from "graphql-subscriptions";
export const resolvers = {
Subscription: {
somethingChanged: {
subscribe: withFilter(
(_, args) =>
pubsub.asyncIterator(`${SOMETHING_CHANGED_TOPIC}.${args.relevantId}`),
(payload, variables) =>
payload.somethingChanged.id === variables.relevantId
),
},
},
};
import { AblyPubSub } from "graphql-ably-pubsub";
const pubSub = new AblyPubSub(options, channelName, pubSubClient);
These are the options which are passed to the internal or passed Ably PubSub client. Example -
const options = {
key: "<YOUR-ABLY-API-KEY>",
};
If specified, this channel name is used for every trigger otherwise the trigger itself is used as the channel name. Example -
const channel = "ably-subscription-channel";
If specified, then this client will be used and the options
param value will be ignored.
Example -
const options = {
key: "<YOUR-ABLY-API-KEY>",
};
const pubSubClient = new Ably.Realtime(options);
This project is mostly inspired by graphql-redis-subscriptions and graphql-google-pubsub. Thanks to its authors for their work and inspiration.