Registry / messaging / graphql-mongodb-subscriptions

graphql-mongodb-subscriptions

library1.0.1jsnpmunverified

A PubSub engine for graphql-subscriptions that uses MongoDB's capped collections and tailable cursors to broadcast subscription events across multiple server instances. Current stable version is 1.0.1, with peer dependencies on graphql-subscriptions (^1.0.0 || ^2.0.0) and mongodb (^5.3.0). It implements the PubSubEngine and AsyncIterator interfaces to integrate seamlessly with Apollo GraphQL subscriptions. Key differentiators: leverages MongoDB’s native pub/sub-like capped collection feature for persistence and scalability without additional message brokers. Suitable for stacks already using MongoDB.

messaging database

npm install graphql-mongodb-subscriptions

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-MONGODB-SU

graphql-mongodb-subscriptions

messagingjavascriptv1.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MongodbPubSub

✓ import { MongodbPubSub } from 'graphql-mongodb-subscriptions';

✗ const MongodbPubSub = require('graphql-mongodb-subscriptions');

Package ships TypeScript types; ESM import is preferred. CJS require returns an object with MongodbPubSub property.

PubSubMongoDbOptions

✓ import { PubSubMongoDbOptions } from 'graphql-mongodb-subscriptions';

TypeScript type for constructor options object, used for type annotations only.

withFilter

✓ import { withFilter } from 'graphql-subscriptions';

✗ import { withFilter } from 'graphql-mongodb-subscriptions';

withFilter is re-exported from graphql-subscriptions; do not import from this package.

Shows how to create a MongodbPubSub instance with a connected MongoDB Db, and use asyncIterator and publish for a subscription topic.

import { MongodbPubSub } from 'graphql-mongodb-subscriptions'; import { MongoClient } from 'mongodb'; const MONGO_URI = process.env.MONGO_URI ?? 'mongodb://localhost:27017'; const client = new MongoClient(MONGO_URI); await client.connect(); const db = client.db('subscriptions'); const pubsub = new MongodbPubSub({ connectionDb: db }); const TOPIC = 'POST_ADDED'; // In your subscription resolver: const resolvers = { Subscription: { postAdded: { subscribe: () => pubsub.asyncIterator(TOPIC), }, }, }; // Publish an event: pubsub.publish(TOPIC, { postAdded: { id: '123', title: 'Hello' } });

Debug

Known issues

breakingMongoDB driver v5 changes: connection string options and topology may affect pubsub behavior.

fix

Ensure MongoDB driver is v5.x compatible. For older drivers, version pinning may be required.

affects: >=1.0.0

gotchaRequires a pre-existing MongoDB database; the pubsub creates a capped collection but will fail if connectionDb is not provided.

fix

Always provide connectionDb via options. The database must already exist.

affects: >=0.0.0

deprecatedgraphql-subscriptions v2 uses @graphql-yoga/common for subscriptions; this package may not be fully compatible with Apollo Server 4 or newer subscription resolvers.

fix

Test with your GraphQL server version. Consider using @graphql-yoga or Apollo Server 4 integration plugins.

affects: >=1.0.0

gotchaCapped collection size/max defaults may cause events to be dropped if not configured properly.

fix

Set channelOptions.size and channelOptions.max to appropriate values for your throughput.

affects: >=0.0.0

gotchaAsyncIterator uses tailable cursors; if the capped collection is full, old events are dropped silently.

fix

Monitor collection size and adjust cap settings. Implement retry logic for missed events.

affects: >=0.0.0

Errors

Common errors & fixes

MongoError: Cannot create collection subscriptions.test - collection already exists with different options

The capped collection already exists with different options (e.g., non-capped).

fix

Drop the collection manually: db.collection('test').drop() and allow the library to recreate it.

TypeError: pubsub.asyncIterator is not a function

Importing the library incorrectly (e.g., default import instead of named).

fix

Use `import { MongodbPubSub } from 'graphql-mongodb-subscriptions';`

Error: connectionDb is required

MongodbPubSub instantiated without connectionDb option.

fix

Pass configuration object with connectionDb: db (a Db instance from MongoClient).

MongoServerError: Capped collection size must be a number

channelOptions.size is missing or not a number.

fix

Set channelOptions.size to a valid number (bytes). Default is 1000000 (1MB).

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

graphql-subscriptionsrequiredPeer dependency — provides PubSubEngine interface and withFilter helper.

mongodbrequiredPeer dependency — MongoDB driver for Node.js (v5.x).

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mjwheatley/graphql-mongodb-subscriptions ↗

packagegraphql-mongodb-subscriptions ↗

homepagehttps://github.com/mjwheatley/graphql-mongodb-subscriptions.git ↗