graphql-redis-subscriptions

graphql-redis-subscriptions implements the PubSubEngine interface from Apollo’s graphql-subscriptions package (and the standard AsyncIterator interface) on top of Redis pub/sub. Instead of an in-memory event bus that only works for a single process, it publishes and subscribes through Redis, so any number of GraphQL server instances behind a load balancer can broadcast and receive the same subscription events.

It wraps ioredis publisher and subscriber connections, and supports configuring custom connections, Redis Cluster, custom serializers/deserializers, custom revivers for non-JSON types like dates, and topic patterns for wildcard subscriptions. Because it’s a drop-in PubSubEngine, it plugs into existing Apollo Server or graphql-subscriptions based resolvers with a one-line swap from the default in-memory PubSub.

What You Get

• A RedisPubSub class implementing the PubSubEngine interface from graphql-subscriptions
• asyncIterator() for wiring subscription resolvers via the standard AsyncIterator protocol
• Support for passing custom publisher/subscriber ioredis clients, including Redis Cluster
• Dynamic and pattern-based topic subscriptions for parameterized events (e.g. per-entity channels)
• Configurable serializer, deserializer, and reviver hooks for custom payload (de)serialization
• Support for receiving raw Buffer messages for binary-safe payloads

Common Use Cases

• Scaling a GraphQL subscriptions server horizontally behind a load balancer with shared event delivery
• Filtering subscription events by argument using withFilter from graphql-subscriptions alongside dynamic Redis topics
• Connecting subscriptions to an existing Redis or Redis Cluster deployment already used for caching or sessions
• Migrating from the default in-memory PubSub to a production-ready, multi-instance-safe subscription backend

Under The Hood

Architecture RedisPubSub (in src/redis-pubsub.ts) maintains separate ioredis publisher and subscriber connections; publish() serializes a payload and issues a Redis PUBLISH, while subscribe()/asyncIterator() issue Redis SUBSCRIBE/PSUBSCRIBE and route incoming messages to listeners through pubsub-async-iterator.ts, which adapts the emitter-style callback API to the standard AsyncIterator protocol consumed by GraphQL subscription resolvers. Tech Stack It’s a TypeScript library built on the graphql-subscriptions peer dependency for the PubSubEngine contract and ioredis for the Redis client, compiled with tsc to a dist/ CommonJS output with type declarations. Code Quality Tests live in src/test/tests.ts (unit, run via Mocha with nyc coverage) and src/test/integration-tests.ts (integration tests against a real Redis instance), plus ESLint is run as part of npm test; the library has been stable for years with infrequent but maintained releases. API Design The API surface is intentionally small — a RedisPubSub constructor taking a typed options object (connection, publisher/subscriber, serializer/deserializer, reviver) plus publish/subscribe/asyncIterator methods that match graphql-subscriptions’s own interface, so adopting it is a near drop-in replacement for the default in-memory PubSub.