pg-listener

library1.1.3jsnpmunverified

pg-listener is a lightweight PostgreSQL NOTIFY/LISTEN client designed to work exclusively with pg-promise (v10+). At version 1.1.3, it provides automatic reconnection via retry-async, zero external dependencies besides pg-promise, and full TypeScript support. It simplifies listening to multiple channels on a single connection, supports both event-based and async iterable consumption of notifications, and offers configurable retry strategies for initial and ongoing connections. It differentiates from raw pg-promise usage by abstracting connection management and providing higher-level ergonomics for PostgreSQL notifications.

database

npm install pg-listener

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-LISTENER

pg-listener

databasejavascriptv1.1.3

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.

PgListener

✓ import { PgListener } from 'pg-listener'

✗ const PgListener = require('pg-listener')

ESM-only; compatible with Node >=16 and pg-promise >=10.

IListenEvents

✓ import { IListenEvents } from 'pg-listener'

✗ import { IListenEvents } from 'pg-listener/cjs'

TypeScript type; imported directly from package root.

IListenResult

✓ import { IListenResult } from 'pg-listener'

TypeScript type for the result of listen().

Sets up a pg-promise connection, creates a PgListener, and listens on a PostgreSQL channel with event handler.

import pgPromise from 'pg-promise'; import { PgListener, IListenEvents } from 'pg-listener'; const pgp = pgPromise(); const db = pgp({ host: 'localhost', port: 5432, database: 'mydb', user: 'user', password: process.env.PGPASSWORD ?? '', keepAlive: true }); const listener = new PgListener({ pgp, db }); const events: IListenEvents = { onMessage(msg) { console.log(`Channel: ${msg.channel}, Payload: ${msg.payload}`); } }; async function main() { try { const result = await listener.listen(['my_channel'], events); console.log('Listening on my_channel'); } catch (err) { console.error('Failed to listen:', err); } } main();

Debug

Known issues

gotchaRequires keepAlive on the database connection to prevent timeout on idle connections, especially on cloud providers like AWS.

fix

Set keepAlive: true (and optionally keepAliveInitialDelayMillis) in the pg-promise connection options.

affects: >=1.0.0

gotchaIf you pass no channels to listen(), it creates a connection solely for sending notifications via result.notify().

fix

Use db.none('NOTIFY ...') instead for sending notifications; avoid creating an empty listener unless strictly needed.

affects: >=1.0.0

breakingThe listen() method now returns an object with createIterable and cancel instead of the previous interface. Old code using the result as a stream may break.

fix

Update to use createIterable() or the cancel callback. Refer to the IListenResult type.

affects: >=1.1.0

deprecatedSupport for pg-promise <10 is dropped; installing with older versions will cause peer dependency warnings.

fix

Upgrade pg-promise to version 10 or newer.

affects: >=1.0.0

gotchaRetry options (retryAll, retryInit) override internal defaults; forgetting to set them may lead to longer-than-expected retry delays.

fix

Set explicit retry options if you need predictable retry timing, e.g., retryAll: { retry: 3, delay: () => 1000 }.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'pg-listener'

Missing installation or wrong import path; package is ESM-only.

fix

Run 'npm install pg-listener' and use 'import { PgListener } from 'pg-listener'.

listen is not a function

Importing the default export instead of named export.

fix

Use 'import { PgListener } from 'pg-listener', not 'import PgListener from 'pg-listener'.

Cannot redeclare block-scoped variable 'listener'

Using TypeScript with an outdated tsconfig or no module resolution.

fix

Ensure tsconfig has 'moduleResolution': 'node' and 'esModuleInterop': true.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

pg-promiserequiredPeer dependency; library uses pg-promise for database access and requires version >=10.

Agent activity

7 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/vitaly-t/pg-listener ↗

packagepg-listener ↗

homepagehttps://github.com/vitaly-t/pg-listener ↗