{"_id":"@adliihjs/graphql-postgres-subscriptions","name":"@adliihjs/graphql-postgres-subscriptions","dist-tags":{"latest":"3.0.0"},"versions":{"3.0.0":{"name":"@adliihjs/graphql-postgres-subscriptions","publishConfig":{"access":"public"},"version":"3.0.0","description":"PostgreSQL-backed PubSub implementation for GraphQL subscriptions (graphql-subscriptions v3)","main":"dist/index.js","types":"dist/index.d.ts","license":"MIT","engines":{"node":">=14"},"repository":{"type":"git","url":"git+https://github.com/adliih/graphql-postgres-subscriptions.git"},"peerDependencies":{"graphql":"^15.7.2 || ^16.0.0 || ^17.0.0"},"dependencies":{"graphql-subscriptions":"^3.0.0","pg":"^8.0.0"},"devDependencies":{"@semantic-release/changelog":"^6.0.0","@semantic-release/git":"^10.0.0","@semantic-release/github":"^11.0.0","@semantic-release/npm":"^12.0.0","@types/jest":"^29.0.0","@types/pg":"^8.0.0","graphql":"^16.0.0","jest":"^29.0.0","semantic-release":"^24.0.0","ts-jest":"^29.0.0","typescript":"^5.0.0"},"scripts":{"build":"tsc","prepare":"npm run build","test":"jest --forceExit","prepublishOnly":"npm run build","release":"semantic-release"},"_id":"@adliihjs/graphql-postgres-subscriptions@3.0.0","gitHead":"830cd0c2962e9e7fc05fb95dfd9aebf8ae58df2b","bugs":{"url":"https://github.com/adliih/graphql-postgres-subscriptions/issues"},"homepage":"https://github.com/adliih/graphql-postgres-subscriptions#readme","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-3Sjif4Bc5iVhMfUezepDZn+0RRclx/X0lVIQsE1Q+9orFK/53+PYGQHdByMFZ7M1SYo/aTuwy4v0ngaPHcgE1A==","shasum":"1e93cf216f1b880e66263ec59e3da5249470f5ef","tarball":"https://registry.npmjs.org/@adliihjs/graphql-postgres-subscriptions/-/graphql-postgres-subscriptions-3.0.0.tgz","fileCount":11,"unpackedSize":19949,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCelrwHRH+aSwomKjPp9nEf+IqWD+gh6NCA7jTrQ6COwwIgTWg3dvvWIaUDZzCOFNuBwpofbMu3uQo9pNVFnbkX/9s="}]},"_npmUser":{"name":"adliihjs","email":"npmjs@adliih.com"},"directories":{},"maintainers":[{"name":"adliihjs","email":"npmjs@adliih.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/graphql-postgres-subscriptions_3.0.0_1776219526076_0.9730934456853035"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-15T02:18:45.978Z","3.0.0":"2026-04-15T02:18:46.205Z","modified":"2026-04-15T02:18:46.409Z"},"maintainers":[{"name":"adliihjs","email":"npmjs@adliih.com"}],"description":"PostgreSQL-backed PubSub implementation for GraphQL subscriptions (graphql-subscriptions v3)","homepage":"https://github.com/adliih/graphql-postgres-subscriptions#readme","repository":{"type":"git","url":"git+https://github.com/adliih/graphql-postgres-subscriptions.git"},"bugs":{"url":"https://github.com/adliih/graphql-postgres-subscriptions/issues"},"license":"MIT","readme":"# @adliihjs/graphql-postgres-subscriptions\n\nA graphql subscriptions implementation using postgres and apollo's graphql-subscriptions.\n\nThis package implements the PubSubEngine Interface from the graphql-subscriptions package and also the new AsyncIterator interface. It allows you to connect your subscriptions manger to a postgres based Pub Sub mechanism to support multiple subscription manager instances.\n\n## Installation\n\nThe scoped name is not on the public npm registry yet. Install **from GitHub** (the `prepare` script runs `tsc` so `dist/` exists after install):\n\n```bash\nnpm install github:adliih/graphql-postgres-subscriptions\n```\n\nPin a branch, tag, or commit:\n\n```bash\nnpm install github:adliih/graphql-postgres-subscriptions#main\nnpm install github:adliih/graphql-postgres-subscriptions#v3.0.0\n```\n\nYarn / pnpm equivalents: `yarn add github:adliih/graphql-postgres-subscriptions` or `pnpm add github:adliih/graphql-postgres-subscriptions`.\n\n**Note:** Installing from git relies on this package’s devDependencies (e.g. TypeScript) for the build. Avoid root installs with `npm install --omit=dev` (or production-only CI) unless you vendor a prebuilt copy (e.g. `npm pack` tarball from a release).\n\n### Other ways to distribute\n\n- **GitHub Packages (npm)** — publish to `https://npm.pkg.github.com` with a `GITHUB_TOKEN` / PAT; consumers set `.npmrc` for the scope. No npmjs.com account required beyond GitHub access to the package.\n- **Release assets** — run `npm pack`, attach the `.tgz` to a GitHub Release; consumers run `npm install ./graphql-postgres-subscriptions-3.0.0.tgz`.\n- **Commit `dist/`** — if you need minimal install size and no compile step, stop ignoring `dist/` and commit built output (tradeoff: noisier diffs).\n\n## Usage\n\nExample app: https://github.com/GraphQLCollege/apollo-subscriptions-example\n\nFirst of all, follow the instructions in [graphql-subscriptions](https://github.com/apollographql/graphql-subscriptions) to add subscriptions to your app.\n\nAfterwards replace `PubSub` with `PostgresPubSub`:\n\n```js\n// Before\nimport { PubSub } from \"graphql-subscriptions\";\n\nexport const pubsub = new PubSub();\n```\n\n```js\n// After\nimport { PostgresPubSub } from \"@adliihjs/graphql-postgres-subscriptions\";\n\nexport const pubsub = new PostgresPubSub();\n```\n\nThis library uses [`node-postgres`](https://github.com/brianc/node-postgres) to connect to PostgreSQL. If you want to customize connection options, please refer to their [connection docs](https://node-postgres.com/features/connecting).\n\nYou have three options:\n\nIf you don's send any argument to `new PostgresPubSub()`, we'll create a `postgres` client with no arguments.\n\nYou can also pass [node-postgres connection options](https://node-postgres.com/features/connecting#programmatic) to `PostgresPubSub`.\n\nYou can instantiate your own `client` and pass it to `PostgresPubSub`. Like this:\n\n```js\nimport { PostgresPubSub } from \"@adliihjs/graphql-postgres-subscriptions\";\nimport { Client } from \"pg\";\n\nconst client = new Client();\nawait client.connect();\nconst pubsub = new PostgresPubSub({ client });\n```\n\n**Important**: Don't pass clients from `pg`'s `Pool` to `PostgresPubSub`. As [node-postgres creator states in this StackOverflow answer](https://stackoverflow.com/questions/8484404/what-is-the-proper-way-to-use-the-node-js-postgresql-module), the client needs to be around and not shared so pg can properly handle `NOTIFY` messages (which this library uses under the hood)\n\n### commonMessageHandler\n\nThe second argument to `new PostgresPubSub()` is the `commonMessageHandler`. The common message handler gets called with the received message from PostgreSQL.\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 = () => new DataLoader(...)\nconst commonMessageHandler = ({attributes: {id}, data}) => ({id, dataLoader: getDataLoader()})\nconst pubsub = new PostgresPubSub({ client, commonMessageHandler });\n```\n\n```javascript\nexport const resolvers = {\n  Subscription: {\n    somethingChanged: {\n      resolve: ({ id, dataLoader }) => dataLoader.load(id)\n    }\n  }\n};\n```\n\n## Error handling\n\n`PostgresPubSub` instances emit a special event called `\"error\"`. This event's payload is an instance of Javascript's `Error`. You can get the error's text using `error.message`.\n\n```js\nconst ps = new PostgresPubSub({ client });\n\nps.subscribe(\"error\", err => {\n  console.log(err.message); // -> \"payload string too long\"\n}).then(() => ps.publish(\"a\", \"a\".repeat(9000)));\n```\n\nFor example you can log all error messages (including stack traces and friends) using something like this:\n\n```js\nps.subscribe(\"error\", console.error);\n```\n\n## Development\n\nThis project has an integration test suite that uses [`jest`](https://facebook.github.io/jest/) to make sure everything works correctly.\n\nWe use Docker to spin up a PostgreSQL instance before running the tests. To run them, type the following commands:\n\n- `docker-compose build`\n- `docker-compose run test`\n","readmeFilename":"README.md","_rev":"1-196d6d73f78dc6934ac3bae3f5ea1612"}