V3

.github/workflows/build.yml

@@ -2,16 +2,49 @@ name: Build
 
 on:
   push:
+    branches: [master, v3]
+    tags: ['*']
   pull_request:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  build:
+  quality:
+    name: Lint & format
     runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: npm
 
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check formatting
+        run: npm run format:check
+
+      - name: Lint
+        run: npm run lint
+
+  test:
+    name: Test (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
     strategy:
+      fail-fast: false
       matrix:
-        node-version: [lts/*]
-
+        node-version: [22.x, 24.x]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -20,9 +53,48 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
+          cache: npm
 
       - name: Install dependencies
-        run: npm install
+        run: npm ci
 
       - name: Run tests
         run: npm test
+
+  integration:
+    name: Integration (real PostgreSQL, Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [22.x, 24.x]
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+        ports:
+          - 5432:5432
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run integration tests
+        env:
+          PG_TEST_DSN: postgres://postgres:postgres@localhost:5432/postgres
+        run: npm run test:integration

.npmignore

@@ -47,3 +47,9 @@ tslint.json
 bin/
 .git/
 examples/
+
+# Dev/tooling - never part of the published package
+scripts/
+.oxlintrc.json
+.oxfmtrc.json
+.agent-out/

.oxfmtrc.json

@@ -0,0 +1,9 @@
+{
+  "singleQuote": true,
+  "tabWidth": 4,
+  "printWidth": 80,
+  "semi": true,
+  "trailingComma": "all",
+  "arrowParens": "avoid",
+  "bracketSpacing": true
+}

.oxlintrc.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "categories": {
+    "correctness": "error"
+  },
+  "rules": {
+    "no-debugger": "error",
+    "no-console": ["warn", { "allow": ["warn", "error", "info"] }],
+    "no-unused-vars": "warn"
+  },
+  "ignorePatterns": [
+    "**/*.js",
+    "**/*.d.ts",
+    "docs/",
+    "coverage/",
+    ".nyc_output/",
+    ".agent-out/",
+    "node_modules/"
+  ]
+}

README.md

@@ -256,6 +256,35 @@ enable this feature, you can bypass `executionLock` as option and set it to
 > only notify message. If this important to you and your system will lave data
 > leaks you need to ensure that payloads are unique.
 
+## Operational Notes (since 3.0.0)
+
+- **Error handling**: always subscribe to the `'error'` event. Connection
+  errors are forwarded there; when no listener is attached they are routed
+  to the configured logger instead of crashing the process.
+- **Automatic reconnect** recreates the underlying `pg` client (pg clients
+  are single-use), so construct `PgPubSub` with connection options
+  (`connectionString` etc.) rather than a pre-made `pgClient` instance if
+  you rely on reconnects. Do not cache the `pgClient` reference across
+  reconnects.
+- **Graceful shutdown is opt-in**: importing the package no longer
+  registers process signal handlers. Construct with `handleSignals: true`
+  or call `enableGracefulShutdown()` to get SIGINT/SIGTERM/SIGABRT
+  handling with automatic locks release.
+- **Database privileges**: the first run bootstraps the lock schema
+  (`CREATE SCHEMA/TABLE/FUNCTION/TRIGGER`), which requires DDL rights. In
+  locked-down environments provision it manually beforehand (see the SQL
+  in `src/PgIpLock.ts`) - initialization failures are logged and locking
+  will not work without the schema.
+- **Delivery semantics**: LISTEN/NOTIFY is at-most-once with no backlog -
+  messages published while a subscriber is reconnecting are lost, and
+  `NOTIFY` payloads are limited to 8000 bytes (`notify()` throws a
+  `RangeError` beyond that). Per-message execution locks keep a
+  processed-marker row for one hour (`UNIQUE_LOCK_TTL`) to guarantee
+  exactly-once handling across competing listeners.
+- **Integration tests**: `PG_TEST_DSN=... npm run test:integration` runs
+  the real-PostgreSQL flow suite (also wired into CI with a postgres
+  service container).
+
 ## [Full API Docs](https://github.com/imqueue/pg-pubsub/wiki)
 
 You may read API docs on [wiki pages](https://github.com/imqueue/pg-pubsub/wiki)

index.ts

@@ -21,4 +21,4 @@
  * purchase a proprietary commercial license. Please contact us at
  * <support@imqueue.com> to get commercial licensing options.
  */
-export * from './src';
+export * from './src/index.js';