{"id":22055830,"url":"https://github.com/axelspringer/graphql-google-pubsub","last_synced_at":"2025-04-05T18:11:45.886Z","repository":{"id":30564100,"uuid":"125195559","full_name":"axelspringer/graphql-google-pubsub","owner":"axelspringer","description":"A graphql-subscriptions PubSub Engine using Google PubSub","archived":false,"fork":false,"pushed_at":"2023-04-23T19:06:59.000Z","size":347,"stargazers_count":136,"open_issues_count":20,"forks_count":43,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-29T17:11:11.061Z","etag":null,"topics":["google-pubsub","graphql","graphql-subscriptions"],"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/axelspringer.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-14T10:29:40.000Z","updated_at":"2023-08-27T04:41:09.000Z","dependencies_parsed_at":"2024-06-18T17:02:05.963Z","dependency_job_id":"55e895a7-d88c-4f12-bec2-dae9e74adcf3","html_url":"https://github.com/axelspringer/graphql-google-pubsub","commit_stats":{"total_commits":67,"total_committers":6,"mean_commits":"11.166666666666666","dds":"0.14925373134328357","last_synced_commit":"1a7cb6af9e5dbd0bfdb32ac3a3659054cea58a42"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axelspringer%2Fgraphql-google-pubsub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axelspringer%2Fgraphql-google-pubsub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axelspringer%2Fgraphql-google-pubsub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axelspringer%2Fgraphql-google-pubsub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axelspringer","download_url":"https://codeload.github.com/axelspringer/graphql-google-pubsub/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247378152,"owners_count":20929297,"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":["google-pubsub","graphql","graphql-subscriptions"],"created_at":"2024-11-30T16:11:40.246Z","updated_at":"2025-04-05T18:11:45.869Z","avatar_url":"https://github.com/axelspringer.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# graphql-google-pubsub\n\nThis package implements the PubSubEngine Interface from the [graphql-subscriptions](https://github.com/apollographql/graphql-subscriptions) package and also the new AsyncIterator interface. \nIt allows you to connect your subscriptions manger to a Google PubSub mechanism to support \nmultiple subscription manager instances.\n\n## Installation\n\n`npm install @axelspringer/graphql-google-pubsub` \nor\n`yarn add @axelspringer/graphql-google-pubsub`\n   \n## Using as AsyncIterator\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, let's create a simple `GooglePubSub` instance:\n\n```javascript\nimport { GooglePubSub } from '@axelspringer/graphql-google-pubsub';\nconst pubsub = new GooglePubSub();\n```\n\nNow, implement your Subscriptions type resolver, using the `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\nCalling the method `asyncIterator` of the `GooglePubSub` instance will subscribe to the topic provided and will return an `AsyncIterator` binded to the GooglePubSub instance and listens to any event published on that topic.\nNow, the GraphQL engine knows that `somethingChanged` is a subscription, and every time we will use `pubsub.publish` over this topic, the `GooglePubSub` 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.\n\n```js\npubsub.publish(SOMETHING_CHANGED_TOPIC, { somethingChanged: { id: \"123\" }});\n```\n\nThe topic doesn't get created automatically, it has to be created beforehand.\n\nIf you publish non string data it gets stringified and you have to [parse the received message data](#receive-messages).\n\n## Receive Messages\n\nThe [received message](https://googleapis.dev/nodejs/pubsub/1.1.5/Message.html) from Google PubSub gets directly passed as payload to the resolve/filter function.\n\nYou might extract the data (Buffer) in there or use a [common message handler](#commonmessagehandler) to transform the received message.\n\n```javascript\nfunction commonMessageHandler ({attributes = {}, data = ''}) {\n  return {\n    ...attributes,\n    text: data.toString()\n  };\n}\n```\n\nThe `can use custom message handler` test illustrates the flexibility of the common message handler.\n\n## Dynamically use 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 both 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## Creating the Google PubSub Client\n\n```javascript\nimport { GooglePubSub } from '@axelspringer/graphql-google-pubsub';\n\nconst pubSub = new GooglePubSub(options, topic2SubName, commonMessageHandler)\n```\n\n### Options\nThese are the [options](https://googleapis.dev/nodejs/pubsub/1.1.5/global.html#ClientConfig) which are passed to the internal or passed Google PubSub client.\nThe client will extract credentials, project name etc. from environment variables if provided.\nHave a look at the [authentication guide](https://cloud.google.com/docs/authentication/getting-started) for more information.\nOtherwise you can provide this details in the options.\n```javascript\nconst options = {\n  projectId: 'project-abc',\n  credentials:{\n    client_email: 'client@example-email.iam.gserviceaccount.com',\n    private_key: '-BEGIN PRIVATE KEY-\\nsample\\n-END PRIVATE KEY-\\n'\n  }\n};\n```\n\n#### Subscription Options\n\n[Subscription options](https://googleapis.dev/nodejs/pubsub/1.1.5/global.html#CreateSubscriptionRequest) can be passed into `subscribe` or `asyncInterator`.\n\nNote: [google.protobuf.Duration](https://googleapis.dev/nodejs/pubsub/1.1.5/google.protobuf.html#.Duration) types must be passed in as an object with a seconds property (`{ seconds: 123 }`).\n\n```javascript\nconst dayInSeconds = 60 * 60 * 24;\n\nconst subscriptionOptions = {\n  messageRetentionDuration: { seconds: dayInSeconds },\n  expirationPolicy: {\n    ttl: { seconds: dayInSeconds * 2 }, // 2 Days\n  },\n};\n\nawait pubsub.asyncIterator(\"abc123\", subscriptionOptions);\n```\n\n### topic2SubName\n\nAllows building different workflows. If you listen on multiple server instances to the same subscription, the messages will get distributed between them.\nMost of the time you want different subscriptions per server. That way every server instance can inform their clients about a new message.\n\n```javascript\nconst topic2SubName = topicName =\u003e `${topicName}-${serverName}-subscription`\n```\n\n### commonMessageHandler\n\nThe common message handler gets called with the received message from Google PubSub.\nYou can transform the message before it is passed to the individual filter/resolver methods of the subscribers.\nThis way it is for example possible to inject one instance of a [DataLoader](https://github.com/facebook/dataloader) which can be used in all filter/resolver methods.\n\n```javascript\nconst getDataLoader = () =\u003e new DataLoader(...);\nconst commonMessageHandler = ({attributes: {id}, data}) =\u003e ({id, dataLoader: getDataLoader()});\n```\n\n```javascript\nexport const resolvers = {\n  Subscription: {\n    somethingChanged: {\n      resolve: ({id, dataLoader}) =\u003e dataLoader.load(id)\n    },\n  },\n}\n```\n\n## Author\n\n[Jonas Hackenberg - jonas-arkulpa](https://github.com/jonas-arkulpa)\n\n## Acknowledgements\n\nThis project is mostly inspired by [graphql-redis-subscriptions](https://github.com/davidyaha/graphql-redis-subscriptions).\nMany thanks to its authors for their work and inspiration. Thanks to the Lean Team ([Daniel Vogel](https://github.com/herr-vogel), [Martin Thomas](https://github.com/mthomas87), [Marcel Dohnal](https://github.com/mdohnal), [Florian Tatzky](https://github.com/pferdone), [Sebastian Herrlinger](https://github.com/kommander), [Mircea Craculeac](https://github.com/emzaeh) and [Tim Susa](https://github.com/TimSusa)).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxelspringer%2Fgraphql-google-pubsub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxelspringer%2Fgraphql-google-pubsub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxelspringer%2Fgraphql-google-pubsub/lists"}