{"id":14070468,"url":"https://github.com/andywer/pg-listen","last_synced_at":"2025-05-15T11:08:47.368Z","repository":{"id":33068325,"uuid":"150887094","full_name":"andywer/pg-listen","owner":"andywer","description":"📡 PostgreSQL LISTEN \u0026  NOTIFY for node.js that finally works.","archived":false,"fork":false,"pushed_at":"2024-06-11T10:40:25.000Z","size":423,"stargazers_count":612,"open_issues_count":13,"forks_count":31,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-11T20:00:01.946Z","etag":null,"topics":["events","message-passing","nodejs","notifications","postgresql","pubsub","typescript"],"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/andywer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"andywer","patreon":"andywer","open_collective":null,"ko_fi":"andywer","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2018-09-29T17:24:15.000Z","updated_at":"2025-04-02T11:54:14.000Z","dependencies_parsed_at":"2024-06-11T12:09:02.713Z","dependency_job_id":null,"html_url":"https://github.com/andywer/pg-listen","commit_stats":{"total_commits":83,"total_committers":8,"mean_commits":10.375,"dds":"0.45783132530120485","last_synced_commit":"42654a40de14cf1e1d30179587d588583a29181b"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpg-listen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpg-listen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpg-listen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpg-listen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andywer","download_url":"https://codeload.github.com/andywer/pg-listen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328385,"owners_count":22052632,"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":["events","message-passing","nodejs","notifications","postgresql","pubsub","typescript"],"created_at":"2024-08-13T07:07:47.205Z","updated_at":"2025-05-15T11:08:47.348Z","avatar_url":"https://github.com/andywer.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003epg-listen\u003c/h1\u003e\n\u003ch3 align=\"center\"\u003ePostgres LISTEN \u0026 NOTIFY that works\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://travis-ci.org/andywer/pg-listen\"\u003e\n    \u003cimg alt=\"Build Status\" src=\"https://travis-ci.org/andywer/pg-listen.svg?branch=master\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/pg-listen\"\u003e\n    \u003cimg alt=\"NPM Version\" src=\"https://img.shields.io/npm/v/pg-listen.svg\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr /\u003e\n\nPostgreSQL can act as a message broker: Send notifications with arbitrary payloads from one database client to others.\n\nWorks with node.js 8+ and plain JavaScript or TypeScript 3. Uses the Postgres [`NOTIFY`](https://www.postgresql.org/docs/10/static/sql-notify.html) statement and subscribes to notifications using [`LISTEN`](https://www.postgresql.org/docs/10/static/sql-listen.html).\n\n### Features\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;📡\u0026nbsp;\u0026nbsp;Send and subscribe to messages\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;⏳\u0026nbsp;\u0026nbsp;Continuous connection health checks\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;♻️\u0026nbsp;\u0026nbsp;Reconnects automatically\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;❗️\u0026nbsp;\u0026nbsp;Proper error handling\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;👌\u0026nbsp;\u0026nbsp;Type-safe API\n\n---\n\n\n## Installation\n\n```sh\n# using npm:\nnpm install pg-listen\n\n# using yarn:\nyarn add pg-listen\n```\n\n\n## Usage\n\n```js\nimport createSubscriber from \"pg-listen\"\nimport { databaseURL } from \"./config\"\n\n// Accepts the same connection config object that the \"pg\" package would take\nconst subscriber = createSubscriber({ connectionString: databaseURL })\n\nsubscriber.notifications.on(\"my-channel\", (payload) =\u003e {\n  // Payload as passed to subscriber.notify() (see below)\n  console.log(\"Received notification in 'my-channel':\", payload)\n})\n\nsubscriber.events.on(\"error\", (error) =\u003e {\n  console.error(\"Fatal database connection error:\", error)\n  process.exit(1)\n})\n\nprocess.on(\"exit\", () =\u003e {\n  subscriber.close()\n})\n\nexport async function connect () {\n  await subscriber.connect()\n  await subscriber.listenTo(\"my-channel\")\n}\n\nexport async function sendSampleMessage () {\n  await subscriber.notify(\"my-channel\", {\n    greeting: \"Hey, buddy.\",\n    timestamp: Date.now()\n  })\n}\n```\n\n\n## API\n\nFor details see [dist/index.d.ts](./dist/index.d.ts).\n\n\n## Error \u0026 event handling\n\n#### `instance.events.on(\"connected\", listener: () =\u003e void)`\n\nThe `connected` event is emitted once after initially establishing the connection and later once after every successful reconnect. Reconnects happen automatically when `pg-listen` detects that the connection closed or became unresponsive.\n\n#### `instance.events.on(\"error\", listener: (error: Error) =\u003e void)`\n\nAn `error` event is emitted for fatal errors that affect the notification subscription. A standard way of handling those kinds of errors would be to `console.error()`-log the error and terminate the process with a non-zero exit code.\n\nThis `error` event is usually emitted after multiple attempts to reconnect have failed.\n\n#### `instance.events.on(\"notification\", listener: ({ channel, payload }) =\u003e void)`\n\nEmitted whenever a notification is received. You must have subscribed to that channel before using `instance.listenTo()` in order to receive notifications.\n\nA more convenient way of subscribing to notifications is the `instance.notifications` event emitter.\n\n#### `instance.events.on(\"reconnect\", listener: (attempt: number) =\u003e void)`\n\nEmitted when a connection issue has been detected and an attempt to re-connect to the database is started.\n\n#### `instance.notifications.on(channelName: string, listener: (payload: any) =\u003e void)`\n\nThe convenient way of subscribing to notifications. Don't forget to call `.listenTo(channelName)` to subscribe the Postgres client to this channel in order to receive notifications.\n\n\n## Why another package?\n\nIn one sentence: Because none of the existing packages was working reliably in production.\n\nUsing the `NOTIFY` and `LISTEN` features is not trivial using [`node-postgres` (`pg`)](https://www.npmjs.com/package/pg) directly, since you cannot use connection pools and even distinct client connections also tend to time out.\n\nThere are already a few packages out there, like `pg-pubsub`, but neither of them seems to work reliably. Errors are being swallowed, the code is hard to reason about, there is no type-safety, ...\n\nThis package aims to fix those shortcomings. Postgres LISTEN \u0026 NOTIFY in node that finally works.\n\n\n## Debugging\n\nSet the `DEBUG` environment variable to `pg-listen:*` to enable debug logging.\n\n\n## License\n\nMIT\n","funding_links":["https://github.com/sponsors/andywer","https://patreon.com/andywer","https://ko-fi.com/andywer"],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandywer%2Fpg-listen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandywer%2Fpg-listen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandywer%2Fpg-listen/lists"}