pg-trx-outbox

library0.19.256jsnpmunverified

A Node.js library implementing the transactional outbox pattern on PostgreSQL with basic event sourcing support. Current stable version is 0.19.256, released on an ongoing cadence. It provides short-polling and LISTEN/NOTIFY modes for message delivery, supports commands and events handled by multiple consumers, and integrates with custom adapters. Key differentiators include built-in event sourcing primitives, row locking for at-least-once delivery, and a rich set of configuration options. The library ships TypeScript definitions.

database messaging

npm install pg-trx-outbox

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-TRX-OUTBOX

pg-trx-outbox

databasejavascriptv0.19.256

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.

PgTrxOutbox

✓ import { PgTrxOutbox } from 'pg-trx-outbox'

✗ const PgTrxOutbox = require('pg-trx-outbox')

Default export not available; always use named import. ESM-only, no CommonJS support.

PgTrxOutboxOptions

✓ import type { PgTrxOutboxOptions } from 'pg-trx-outbox'

Type import for TypeScript users; not a runtime value.

Adapter

✓ import { Adapter } from 'pg-trx-outbox'

✗ import { MyOwnAdapter } from 'pg-trx-outbox'

Adapter is the base class/interface; custom adapters extend it and are imported from user code, not the library.

Creates and starts a PgTrxOutbox instance with short polling mode, then stops after 10 seconds.

import { PgTrxOutbox } from 'pg-trx-outbox'; import { Pool } from 'pg'; const pool = new Pool(); const pgTrxOutbox = new PgTrxOutbox({ pgOptions: { pool }, adapter: { async onMessages(msgs) { console.log('Messages:', msgs); }, }, outboxOptions: { mode: 'short-polling', pollInterval: 5000, limit: 50 }, }); await pgTrxOutbox.start(); console.log('Outbox started'); setTimeout(() => pgTrxOutbox.stop(), 10000);

Debug

Known issues

breakingv0.17.0 changed the adapter interface; onMessages now receives an array instead of single message.

fix

Update adapter's onMessages method to accept an array of messages.

affects: <0.17.0

deprecatedThe 'pgOptions' option accepting a PoolConfig object is deprecated in favor of passing a Pool instance directly.

fix

Pass a Pool instance to pgOptions instead of a PoolConfig object.

affects: >=0.18.0

gotchaThe 'notify' mode requires the pg-listen package and a database trigger. Missing either will cause silent failures.

fix

Install pg-listen, create the SQL trigger as documented, and ensure function exists.

affects: >=0.0.0

gotchaTable name is hardcoded as 'pg_trx_outbox'; cannot be changed via configuration.

fix

Use the provided migration script and avoid renaming the table.

affects: >=0.0.0

Errors

Common errors & fixes

Error: listen() callback expected handler to be a function

Using notify mode without passing the pg-listen instance correctly; adapter not provided.

fix

Ensure pg-listen is installed and configured properly; check outboxOptions and adapter initialization.

TypeError: Cannot destructure property 'pool' of 'undefined' as it is undefined.

Missing or incorrect pgOptions configuration; pool not passed.

fix

Pass a valid Pool instance to pgOptions: `pgOptions: { pool: new Pool() }`.

Error: relation "pg_trx_outbox" does not exist

The required table has not been created in the database.

fix

Run the CREATE TABLE migration provided in the documentation.

Upgrade

Version history

0.19.256latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client driver for database connections

pg-pooloptionalConnection pooling for PostgreSQL

pg-listenoptionalRequired for notify mode to use LISTEN/NOTIFY

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubssh://git@github.com/darky/pg-trx-outbox ↗

packagepg-trx-outbox ↗

homepagehttps://github.com/darky/pg-trx-outbox#readme ↗