{"id":20562555,"url":"https://github.com/davidyaha/graphql-mqtt-subscriptions","last_synced_at":"2025-04-06T03:10:35.214Z","repository":{"id":54450789,"uuid":"80538622","full_name":"davidyaha/graphql-mqtt-subscriptions","owner":"davidyaha","description":"graphql-subscriptions implementation for MQTT protocol","archived":false,"fork":false,"pushed_at":"2021-02-18T19:53:25.000Z","size":118,"stargazers_count":149,"open_issues_count":9,"forks_count":40,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-18T09:47:15.226Z","etag":null,"topics":["graphql","graphql-subscriptions","mqtt","nodejs"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidyaha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-31T16:29:33.000Z","updated_at":"2024-05-08T00:29:44.000Z","dependencies_parsed_at":"2022-08-13T16:01:05.496Z","dependency_job_id":null,"html_url":"https://github.com/davidyaha/graphql-mqtt-subscriptions","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidyaha%2Fgraphql-mqtt-subscriptions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidyaha%2Fgraphql-mqtt-subscriptions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidyaha%2Fgraphql-mqtt-subscriptions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidyaha%2Fgraphql-mqtt-subscriptions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidyaha","download_url":"https://codeload.github.com/davidyaha/graphql-mqtt-subscriptions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427006,"owners_count":20937201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graphql","graphql-subscriptions","mqtt","nodejs"],"created_at":"2024-11-16T04:11:37.369Z","updated_at":"2025-04-06T03:10:35.191Z","avatar_url":"https://github.com/davidyaha.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# graphql-mqtt-subscriptions\n\n[![Greenkeeper badge](https://badges.greenkeeper.io/davidyaha/graphql-mqtt-subscriptions.svg)](https://greenkeeper.io/)\n\nThis package implements the AsyncIterator Interface and PubSubEngine Interface from the [graphql-subscriptions](https://github.com/apollographql/graphql-subscriptions) package. \nIt allows you to connect your subscriptions manager to an MQTT enabled Pub Sub broker to support \n\nhorizontally scalable subscriptions setup.\nThis package is an adapted version of my [graphql-redis-subscriptions](https://github.com/davidyaha/graphql-redis-subscriptions) package.\n\n## Installation\n\n```\nnpm install graphql-mqtt-subscriptions\n```\n\n## Using the AsyncIterator Interface\n\nDefine your GraphQL schema with a `Subscription` type.\n\n```graphql\nschema {\n  query: Query\n  mutation: Mutation\n  subscription: Subscription\n}\n\ntype Subscription {\n    somethingChanged: Result\n}\n\ntype Result {\n    id: String\n}\n```\n\nNow, create a `MQTTPubSub` instance.\n\n```javascript\nimport { MQTTPubSub } from 'graphql-mqtt-subscriptions';\nconst pubsub = new MQTTPubSub(); // connecting to mqtt://localhost by default\n```\n\nNow, implement the Subscriptions type resolver, using `pubsub.asyncIterator` to map the event you need.\n\n```javascript\nconst SOMETHING_CHANGED_TOPIC = 'something_changed';\n\nexport const resolvers = {\n  Subscription: {\n    somethingChanged: {\n      subscribe: () =\u003e pubsub.asyncIterator(SOMETHING_CHANGED_TOPIC)\n    }\n  }\n}\n```\n\n\u003e Subscriptions resolvers are not a function, but an object with `subscribe` method, that returns `AsyncIterable`.\n\nThe `AsyncIterator` method will tell the MQTT client to listen for messages from the MQTT broker on the topic provided, and wraps that listener in an `AsyncIterator` object. \n\nWhen messages are received from the topic, those messages can be returned back to connected clients.\n\n`pubsub.publish` can be used to send messages to a given topic.\n\n```js\npubsub.publish(SOMETHING_CHANGED_TOPIC, { somethingChanged: { id: \"123\" }});\n```\n\n## Dynamically Create a Topic Based on Subscription Args Passed on the Query:\n\n```javascript\nexport const resolvers = {\n  Subscription: {\n    somethingChanged: {\n      subscribe: (_, args) =\u003e pubsub.asyncIterator(`${SOMETHING_CHANGED_TOPIC}.${args.relevantId}`),\n    },\n  },\n}\n```\n\n## Using Arguments and Payload to Filter Events\n\n```javascript\nimport { withFilter } from 'graphql-subscriptions';\n\nexport const resolvers = {\n  Subscription: {\n    somethingChanged: {\n      subscribe: withFilter(\n        (_, args) =\u003e pubsub.asyncIterator(`${SOMETHING_CHANGED_TOPIC}.${args.relevantId}`),\n        (payload, variables) =\u003e payload.somethingChanged.id === variables.relevantId,\n      ),\n    },\n  },\n}\n```\n\n## Passing your own client object\n\nThe basic usage is great for development and you will be able to connect to any mqtt enabled server running on your system seamlessly.\nFor production usage, it is recommended you pass your own MQTT client.\n \n```javascript\nimport { connect } from 'mqtt';\nimport { MQTTPubSub } from 'graphql-mqtt-subscriptions';\n\nconst client = connect('mqtt://test.mosquitto.org', {\n  reconnectPeriod: 1000,\n});\n\nconst pubsub = new MQTTPubSub({\n  client\n});\n```\n\nYou can learn more on the mqtt options object [here](https://github.com/mqttjs/MQTT.js#client).\n\n## Changing QoS for publications or subscriptions\n\nAs specified [here](https://github.com/mqttjs/MQTT.js#publish), the MQTT.js publish and subscribe functions takes an \noptions object. This object can be defined per trigger with `publishOptions` and `subscribeOptions` resolvers.\n\n```javascript\nconst triggerToQoSMap = {\n  'comments.added': 1,\n  'comments.updated': 2,\n};\n\nconst pubsub = new MQTTPubSub({\n  publishOptions: trigger =\u003e Promise.resolve({ qos: triggerToQoSMap[trigger] }),\n  \n  subscribeOptions: (trigger, channelOptions) =\u003e Promise.resolve({ \n    qos: Math.max(triggerToQoSMap[trigger], channelOptions.maxQoS), \n  }),\n});\n```\n\n## Get Notified of the Actual QoS Assigned for a Subscription\n\nMQTT allows the broker to assign different QoS levels than the one requested by the client. \nIn order to know what QoS was given to your subscription, you can pass in a callback called `onMQTTSubscribe`\n\n```javascript\nconst onMQTTSubscribe = (subId, granted) =\u003e {\n  console.log(`Subscription with id ${subId} was given QoS of ${granted.qos}`);\n}\n\nconst pubsub = new MQTTPubSub({onMQTTSubscribe});\n```\n\n## Change Encoding Used to Encode and Decode Messages\n\nSupported encodings available [here](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) \n\n```javascript\nconst pubsub = new MQTTPubSub({\n  parseMessageWithEncoding: 'utf16le',\n});\n```\n\n\n## Basic Usage with SubscriptionManager (Deprecated)\n\n```javascript\nimport { MQTTPubSub } from 'graphql-mqtt-subscriptions';\nconst pubsub = new MQTTPubSub(); // connecting to mqtt://localhost on default\nconst subscriptionManager = new SubscriptionManager({\n  schema,\n  pubsub,\n  setupFunctions: {},\n});\n```\n\n## Using Trigger Transform (Deprecated)\n\nSimilar to the [graphql-redis-subscriptions](https://github.com/davidyaha/graphql-redis-subscriptions) package, this package supports\na trigger transform function. This trigger transform allows you to use the `channelOptions` object provided to the `SubscriptionManager`\ninstance, and return a trigger string which is more detailed then the regular trigger. \n\nHere is an example of a generic trigger transform.\n\n```javascript\nconst triggerTransform = (trigger, { path }) =\u003e [trigger, ...path].join('.');\n```\n\n\u003e Note that a `path` field to be passed to the `channelOptions` but you can do whatever you want.\n\nNext, pass the `triggerTransform` to the `MQTTPubSub` constructor.\n\n```javascript\nconst pubsub = new MQTTPubSub({\n  triggerTransform,\n});\n```\n\nLastly, a setupFunction is provided for the `commentsAdded` subscription field.\nIt specifies one trigger called `comments.added` and it is called with the `channelOptions` object that holds `repoName` path fragment.\n```javascript\nconst subscriptionManager = new SubscriptionManager({\n  schema,\n  setupFunctions: {\n    commentsAdded: (options, { repoName }) =\u003e ({\n      'comments/added': {\n        channelOptions: { path: [repoName] },\n      },\n    }),\n  },\n  pubsub,\n});\n```\n\u003e Note that the `triggerTransform` dependency on the `path` field is satisfied here.\n\nWhen `subscribe` is called like this:\n\n```javascript\nconst query = `\n  subscription X($repoName: String!) {\n    commentsAdded(repoName: $repoName)\n  }\n`;\nconst variables = {repoName: 'graphql-mqtt-subscriptions'};\nsubscriptionManager.subscribe({ query, operationName: 'X', variables, callback });\n```\n\nThe subscription string that MQTT will receive will be `comments.added.graphql-mqtt-subscriptions`.\nThis subscription string is much more specific and means the the filtering required for this type of subscription is not needed anymore.\nThis is one step towards lifting the load off of the graphql api server regarding subscriptions.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidyaha%2Fgraphql-mqtt-subscriptions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidyaha%2Fgraphql-mqtt-subscriptions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidyaha%2Fgraphql-mqtt-subscriptions/lists"}