@outbox-event-bus/postgres-drizzle-outbox 1.0.0

package/README.md

@@ -0,0 +1,446 @@
+# PostgreSQL (Drizzle) Outbox
+
+![npm version](https://img.shields.io/npm/v/@outbox-event-bus/postgres-drizzle-outbox?style=flat-square&color=2563eb)
+![npm downloads](https://img.shields.io/npm/dm/@outbox-event-bus/postgres-drizzle-outbox?style=flat-square&color=2563eb)
+![license](https://img.shields.io/npm/l/@outbox-event-bus/postgres-drizzle-outbox?style=flat-square&color=2563eb)
+
+> **Type-Safe PostgreSQL Outbox with Drizzle ORM**
+> 
+> Zero-config setup with automatic schema inference. Custom table support for existing databases.
+
+PostgreSQL adapter for [outbox-event-bus](https://github.com/dunika/outbox-event-bus#readme) using [Drizzle ORM](https://orm.drizzle.team/). Provides robust event storage with `SELECT FOR UPDATE SKIP LOCKED` for safe distributed processing.
+
+```typescript
+import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+import { PostgresDrizzleOutbox } from '@outbox-event-bus/postgres-drizzle-outbox';
+
+const client = postgres(process.env.DATABASE_URL!);
+const db = drizzle(client);
+
+const outbox = new PostgresDrizzleOutbox({
+  db
+});
+```
+
+## Contents
+
+- [When to Use](#when-to-use)
+- [Installation](#installation)
+- [Database Schema](#database-schema)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Custom Table Schemas](#custom-table-schemas)
+- [Advanced Patterns](#advanced-patterns)
+- [Features](#features)
+- [Troubleshooting](#troubleshooting)
+
+## When to Use
+
+**Choose Postgres Drizzle Outbox when:**
+- You are using **PostgreSQL** as your primary database
+- You prefer **SQL-first** development with type safety
+- You need **custom table names** or schemas (multi-tenant apps)
+- You want **zero magic** - explicit queries you can inspect
+
+**Choose Postgres Prisma Outbox instead if:**
+- You're already using Prisma Client
+- You prefer schema-first development with migrations
+- You need Prisma's advanced features (middleware, extensions)
+
+### Performance Characteristics
+
+- **Concurrency**: Uses `SELECT FOR UPDATE SKIP LOCKED` for lock-free event claiming
+- **Throughput**: ~1000-5000 events/sec (single instance, depends on handler complexity)
+- **Latency**: Sub-100ms from emit to handler execution (default polling: 1s)
+
+## Installation
+
+```bash
+npm install @outbox-event-bus/postgres-drizzle-outbox drizzle-orm postgres
+```
+
+## Database Schema
+
+Run the following SQL to create the required tables:
+
+```sql
+CREATE TABLE outbox_events (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  payload JSONB NOT NULL,
+  occurred_at TIMESTAMP NOT NULL,
+  status TEXT NOT NULL DEFAULT 'created',
+  retry_count INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  next_retry_at TIMESTAMP,
+  created_on TIMESTAMP NOT NULL DEFAULT NOW(),
+  started_on TIMESTAMP,
+  keep_alive TIMESTAMP,
+  expire_in_seconds INTEGER NOT NULL DEFAULT 300
+);
+
+CREATE TABLE outbox_events_archive (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  payload JSONB NOT NULL,
+  occurred_at TIMESTAMP NOT NULL,
+  status TEXT NOT NULL,
+  retry_count INTEGER NOT NULL,
+  last_error TEXT,
+  created_on TIMESTAMP NOT NULL,
+  started_on TIMESTAMP,
+  completed_on TIMESTAMP NOT NULL
+);
+
+CREATE INDEX idx_outbox_events_status_retry ON outbox_events (status, next_retry_at);
+CREATE INDEX idx_outbox_events_keepalive ON outbox_events (status, keep_alive);
+```
+
+## Concurrency & Locking
+
+This adapter uses **Row-Level Locking** (`SELECT ... FOR UPDATE SKIP LOCKED`) to ensure safe concurrent processing.
+
+-   **Multiple Workers**: You can run multiple instances of your application.
+-   **No Duplicates**: The database ensures that only one worker picks up a specific event at a time.
+-   **Performance**: `SKIP LOCKED` allows workers to skip locked rows and process the next available event immediately, preventing contention.
+
+## Configuration
+
+### PostgresDrizzleOutboxConfig
+
+| Parameter | Type | Default | Description |
+|:---|:---|:---:|:---|
+| `db` | `PostgresJsDatabase` | **Required** | Drizzle database instance (from `drizzle-orm/postgres-js`) |
+| `getTransaction` | `() => PostgresJsDatabase \| undefined` | `undefined` | Function to retrieve active transaction from AsyncLocalStorage or context |
+| `tables` | `{ outboxEvents, outboxEventsArchive }` | Default schema | Custom Drizzle table definitions (see [Custom Schemas](#custom-table-schemas)) |
+| `maxRetries` | `number` | `5` | Maximum retry attempts before marking event as failed |
+| `baseBackoffMs` | `number` | `1000` | Base delay for exponential backoff (1s, 2s, 4s, 8s, 16s) |
+| `processingTimeoutMs` | `number` | `30000` | Time before reclaiming stuck events (30s) |
+| `pollIntervalMs` | `number` | `1000` | Polling frequency for new events (1s) |
+| `batchSize` | `number` | `50` | Events claimed per poll cycle |
+| `maxErrorBackoffMs` | `number` | `30000` | Maximum backoff delay for polling errors |
+
+> [!TIP]
+> Start with defaults and tune based on metrics. Increase `batchSize` and decrease `pollIntervalMs` for higher throughput.
+
+> [!WARNING]
+> Setting `pollIntervalMs` too low (<100ms) can cause excessive database load. Monitor CPU and connection pool usage.
+
+## Usage
+
+### 1. Basic Setup (No Transactions)
+
+```typescript
+import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+import { PostgresDrizzleOutbox } from '@outbox-event-bus/postgres-drizzle-outbox';
+import { OutboxEventBus } from 'outbox-event-bus';
+
+const client = postgres(process.env.DATABASE_URL!);
+const db = drizzle(client);
+
+const outbox = new PostgresDrizzleOutbox({ db });
+const bus = new OutboxEventBus(outbox, (error) => console.error(error));
+
+bus.on('user.created', async (event) => {
+  await emailService.sendWelcome(event.payload.email);
+});
+
+bus.start();
+
+// Emit without transaction (event saved separately)
+await bus.emit({ 
+  type: 'user.created', 
+  payload: { email: 'user@example.com' } 
+});
+```
+
+> [!WARNING]
+> Without transactions, events are **not atomic** with your data changes. Use transactions for critical workflows.
+
+### 2. Explicit Transactions
+
+```typescript
+await db.transaction(async (tx) => {
+  await tx.insert(users).values(newUser);
+  
+  // Pass transaction explicitly
+  await bus.emit({ 
+    type: 'user.created', 
+    payload: newUser 
+  }, tx);
+});
+```
+
+### 3. AsyncLocalStorage (Recommended)
+
+Avoid passing transactions manually by using AsyncLocalStorage:
+
+```typescript
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+
+const als = new AsyncLocalStorage<PostgresJsDatabase<Record<string, unknown>>>();
+
+const outbox = new PostgresDrizzleOutbox({
+  db,
+  getTransaction: () => als.getStore()
+});
+
+const bus = new OutboxEventBus(outbox, (error) => console.error(error));
+
+// In your service
+async function createUser(user: any) {
+  return await db.transaction(async (tx) => {
+    return await als.run(tx, async () => {
+      await tx.insert(users).values(user);
+      
+      // Bus automatically uses transaction from ALS
+      await bus.emit({ 
+        type: 'user.created', 
+        payload: user 
+      });
+      
+      return user;
+    });
+  });
+}
+```
+
+> [!TIP]
+> AsyncLocalStorage eliminates the need to pass transactions through your call stack, improving code clarity.
+
+## Custom Table Schemas
+
+The adapter supports custom table definitions, enabling:
+- **Multi-tenancy**: Separate outbox tables per tenant
+- **Legacy databases**: Integrate with existing table structures
+- **Custom columns**: Add application-specific metadata
+
+### Example: Custom Table Names
+
+```typescript
+import { pgTable, text, jsonb, timestamp, integer, uuid } from 'drizzle-orm/pg-core';
+
+// Define custom tables
+const myCustomOutbox = pgTable('tenant_a_outbox', {
+  id: uuid('id').primaryKey(),
+  type: text('type').notNull(),
+  payload: jsonb('payload').notNull(),
+  occurredAt: timestamp('occurred_at').notNull(),
+  status: text('status').notNull().default('created'),
+  retryCount: integer('retry_count').notNull().default(0),
+  lastError: text('last_error'),
+  nextRetryAt: timestamp('next_retry_at'),
+  createdOn: timestamp('created_on').notNull().defaultNow(),
+  startedOn: timestamp('started_on'),
+  keepAlive: timestamp('keep_alive'),
+  expireInSeconds: integer('expire_in_seconds').notNull().default(30),
+});
+
+const myCustomArchive = pgTable('tenant_a_archive', {
+  id: uuid('id').primaryKey(),
+  type: text('type').notNull(),
+  payload: jsonb('payload').notNull(),
+  occurredAt: timestamp('occurred_at').notNull(),
+  status: text('status').notNull(),
+  retryCount: integer('retry_count').notNull(),
+  lastError: text('last_error'),
+  createdOn: timestamp('created_on').notNull(),
+  startedOn: timestamp('started_on'),
+  completedOn: timestamp('completed_on').notNull(),
+});
+
+// Use custom tables
+const outbox = new PostgresDrizzleOutbox({
+  db,
+  tables: {
+    outboxEvents: myCustomOutbox,
+    outboxEventsArchive: myCustomArchive
+  }
+});
+```
+
+> [!IMPORTANT]
+> Custom tables **must** include all required columns with compatible types. Missing columns will cause runtime errors.
+
+### Required Schema Fields
+
+| Column | Type | Constraints | Purpose |
+|:---|:---|:---|:---|
+| `id` | `uuid` or `text` | Primary Key | Unique event identifier |
+| `type` | `text` | Not Null | Event type for routing |
+| `payload` | `jsonb` | Not Null | Event data |
+| `occurredAt` | `timestamp` | Not Null | Event timestamp |
+| `status` | `text` | Not Null, Default: 'created' | Lifecycle state |
+| `retryCount` | `integer` | Not Null, Default: 0 | Retry attempts |
+| `lastError` | `text` | Nullable | Error message from last failure |
+| `nextRetryAt` | `timestamp` | Nullable | Scheduled retry time |
+| `createdOn` | `timestamp` | Not Null | Record creation time |
+| `startedOn` | `timestamp` | Nullable | Processing start time |
+| `keepAlive` | `timestamp` | Nullable | Last heartbeat (stuck detection) |
+| `expireInSeconds` | `integer` | Not Null, Default: 30 | Timeout threshold |
+
+## Advanced Patterns
+
+### Monitoring Event Processing
+
+```typescript
+import { OutboxEventBus, MaxRetriesExceededError } from 'outbox-event-bus';
+
+const bus = new OutboxEventBus(outbox, (error: OutboxError) => {
+  // Log to monitoring service
+  const event = error.context?.event;
+  logger.error('Event processing failed', {
+    eventId: event?.id,
+    eventType: event?.type,
+    retryCount: error.context?.retryCount,
+    error: error.message
+  });
+  
+  // Send to Sentry/Datadog
+  if (error instanceof MaxRetriesExceededError) {
+    Sentry.captureException(error, {
+      tags: { eventType: event?.type },
+      extra: { event }
+    });
+  }
+});
+```
+
+### Querying Failed Events
+
+```typescript
+import { eq } from 'drizzle-orm';
+import { outboxEvents } from '@outbox-event-bus/postgres-drizzle-outbox';
+
+// Get all failed events
+const failedEvents = await db
+  .select()
+  .from(outboxEvents)
+  .where(eq(outboxEvents.status, 'failed'))
+  .orderBy(outboxEvents.occurredAt);
+
+// Retry specific events
+const idsToRetry = failedEvents.map(e => e.id);
+await bus.retryEvents(idsToRetry);
+```
+
+### Archive Cleanup (Production)
+
+The adapter automatically archives completed events. For long-running systems, periodically clean old archives:
+
+```sql
+-- Delete archives older than 30 days
+DELETE FROM outbox_events_archive 
+WHERE completed_on < NOW() - INTERVAL '30 days';
+```
+
+Or use a cron job:
+
+```typescript
+import { lt } from 'drizzle-orm';
+import { outboxEventsArchive } from '@outbox-event-bus/postgres-drizzle-outbox';
+
+async function cleanupArchives() {
+  const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+  
+  await db
+    .delete(outboxEventsArchive)
+    .where(lt(outboxEventsArchive.completedOn, thirtyDaysAgo));
+}
+
+// Run daily
+setInterval(cleanupArchives, 24 * 60 * 60 * 1000);
+```
+
+> [!CAUTION]
+> Deleting archives removes audit history. Consider exporting to cold storage (S3, data warehouse) before deletion.
+
+## Features
+
+- **SKIP LOCKED**: Uses `SELECT ... FOR UPDATE SKIP LOCKED` to efficiently claim events without blocking other workers.
+- **Transactional Integrity**: Supports emitting events within the same transaction as your data changes (Atomic Phase 1).
+- **Archiving**: Automatically moves processed events to an archive table to keep the active table small and fast.
+- **Stuck Event Recovery**: Reclaims events that have timed out (stalled workers) based on `keep_alive` + `expire_in_seconds`.
+
+## Troubleshooting
+
+### Events not appearing
+
+**Symptom**: Events emitted but handlers never execute
+
+**Causes**:
+1. **Transaction rollback**: Event was emitted inside a transaction that rolled back
+2. **Bus not started**: Forgot to call `bus.start()`
+3. **No handler registered**: No `bus.on()` for the event type
+
+**Solution**:
+```typescript
+// Ensure bus is started
+bus.start();
+
+// Verify handler is registered
+bus.on('user.created', async (event) => {
+  console.log('Handler called:', event);
+});
+
+// Check transaction commits
+await db.transaction(async (tx) => {
+  await tx.insert(users).values(user);
+  await bus.emit({ type: 'user.created', payload: user }, tx);
+  // Transaction must commit (no throw)
+});
+```
+
+### SerializationFailure / Deadlocks
+
+**Symptom**: `SerializationFailure` errors in logs
+
+**Cause**: High contention on outbox table (multiple workers claiming same events)
+
+**Solution**:
+- The `SKIP LOCKED` clause minimizes this
+- Reduce `pollIntervalMs` to spread out polling
+- Increase `batchSize` to reduce lock frequency
+- Add jitter to polling intervals in multi-worker setups
+
+### High Database Load
+
+**Symptom**: CPU spikes, slow queries
+
+**Cause**: Aggressive polling settings
+
+**Solution**:
+```typescript
+const outbox = new PostgresDrizzleOutbox({
+  db,
+  pollIntervalMs: 2000,  // Increase from 1000ms
+  batchSize: 100         // Process more per poll
+});
+```
+
+### Custom Table Errors
+
+**Symptom**: `column "xyz" does not exist` errors
+
+**Cause**: Custom table schema missing required columns
+
+**Solution**: Ensure your custom table includes all fields from [Required Schema Fields](#required-schema-fields)
+
+### TypeScript Errors with Custom Tables
+
+**Symptom**: Type errors when using custom tables
+
+**Cause**: Table types don't match expected schema
+
+**Solution**:
+```typescript
+// Ensure your table matches the expected structure
+import type { outboxEvents } from '@outbox-event-bus/postgres-drizzle-outbox';
+
+const myTable: typeof outboxEvents = pgTable('custom', {
+  // ... must match outboxEvents structure
+});
+```

package/dist/index.cjs

@@ -0,0 +1,162 @@
+let drizzle_orm = require("drizzle-orm");
+let outbox_event_bus = require("outbox-event-bus");
+let drizzle_orm_pg_core = require("drizzle-orm/pg-core");
+let node_async_hooks = require("node:async_hooks");
+
+//#region src/schema.ts
+const outboxStatusEnum = (0, drizzle_orm_pg_core.pgEnum)("outbox_status", [
+	"created",
+	"active",
+	"completed",
+	"failed"
+]);
+const outboxEvents = (0, drizzle_orm_pg_core.pgTable)("outbox_events", {
+	id: (0, drizzle_orm_pg_core.uuid)("id").primaryKey(),
+	type: (0, drizzle_orm_pg_core.text)("type").notNull(),
+	payload: (0, drizzle_orm_pg_core.jsonb)("payload").notNull(),
+	occurredAt: (0, drizzle_orm_pg_core.timestamp)("occurred_at").notNull(),
+	status: outboxStatusEnum("status").notNull().default("created"),
+	retryCount: (0, drizzle_orm_pg_core.integer)("retry_count").notNull().default(0),
+	lastError: (0, drizzle_orm_pg_core.text)("last_error"),
+	nextRetryAt: (0, drizzle_orm_pg_core.timestamp)("next_retry_at"),
+	createdOn: (0, drizzle_orm_pg_core.timestamp)("created_on").notNull().defaultNow(),
+	startedOn: (0, drizzle_orm_pg_core.timestamp)("started_on"),
+	completedOn: (0, drizzle_orm_pg_core.timestamp)("completed_on"),
+	keepAlive: (0, drizzle_orm_pg_core.timestamp)("keep_alive"),
+	expireInSeconds: (0, drizzle_orm_pg_core.integer)("expire_in_seconds").notNull().default(300)
+});
+const outboxEventsArchive = (0, drizzle_orm_pg_core.pgTable)("outbox_events_archive", {
+	id: (0, drizzle_orm_pg_core.uuid)("id").primaryKey(),
+	type: (0, drizzle_orm_pg_core.text)("type").notNull(),
+	payload: (0, drizzle_orm_pg_core.jsonb)("payload").notNull(),
+	occurredAt: (0, drizzle_orm_pg_core.timestamp)("occurred_at").notNull(),
+	status: outboxStatusEnum("status").notNull(),
+	retryCount: (0, drizzle_orm_pg_core.integer)("retry_count").notNull(),
+	lastError: (0, drizzle_orm_pg_core.text)("last_error"),
+	createdOn: (0, drizzle_orm_pg_core.timestamp)("created_on").notNull(),
+	startedOn: (0, drizzle_orm_pg_core.timestamp)("started_on"),
+	completedOn: (0, drizzle_orm_pg_core.timestamp)("completed_on").notNull()
+});
+
+//#endregion
+//#region src/postgres-drizzle-outbox.ts
+var PostgresDrizzleOutbox = class {
+	config;
+	poller;
+	constructor(config) {
+		this.config = {
+			batchSize: config.batchSize ?? 50,
+			pollIntervalMs: config.pollIntervalMs ?? 1e3,
+			maxRetries: config.maxRetries ?? 5,
+			baseBackoffMs: config.baseBackoffMs ?? 1e3,
+			processingTimeoutMs: config.processingTimeoutMs ?? 3e4,
+			maxErrorBackoffMs: config.maxErrorBackoffMs ?? 3e4,
+			db: config.db,
+			getTransaction: config.getTransaction,
+			tables: config.tables ?? {
+				outboxEvents,
+				outboxEventsArchive
+			}
+		};
+		this.poller = new outbox_event_bus.PollingService({
+			pollIntervalMs: this.config.pollIntervalMs,
+			baseBackoffMs: this.config.baseBackoffMs,
+			maxErrorBackoffMs: this.config.maxErrorBackoffMs,
+			processBatch: (handler) => this.processBatch(handler)
+		});
+	}
+	async publish(events, transaction) {
+		await (transaction ?? this.config.getTransaction?.() ?? this.config.db).insert(this.config.tables.outboxEvents).values(events.map((event) => ({
+			id: event.id,
+			type: event.type,
+			payload: event.payload,
+			occurredAt: event.occurredAt,
+			status: outbox_event_bus.EventStatus.CREATED
+		})));
+	}
+	async getFailedEvents() {
+		return (await this.config.db.select().from(this.config.tables.outboxEvents).where((0, drizzle_orm.eq)(this.config.tables.outboxEvents.status, outbox_event_bus.EventStatus.FAILED)).orderBy(drizzle_orm.sql`${this.config.tables.outboxEvents.occurredAt} DESC`).limit(100)).map((event) => {
+			const failedEvent = {
+				id: event.id,
+				type: event.type,
+				payload: event.payload,
+				occurredAt: event.occurredAt,
+				retryCount: event.retryCount
+			};
+			if (event.lastError) failedEvent.error = event.lastError;
+			if (event.startedOn) failedEvent.lastAttemptAt = event.startedOn;
+			return failedEvent;
+		});
+	}
+	async retryEvents(eventIds) {
+		await this.config.db.update(this.config.tables.outboxEvents).set({
+			status: outbox_event_bus.EventStatus.CREATED,
+			retryCount: 0,
+			nextRetryAt: null,
+			lastError: null
+		}).where((0, drizzle_orm.inArray)(this.config.tables.outboxEvents.id, eventIds));
+	}
+	start(handler, onError) {
+		this.poller.start(handler, onError);
+	}
+	async stop() {
+		await this.poller.stop();
+	}
+	async processBatch(handler) {
+		await this.config.db.transaction(async (transaction) => {
+			const now = /* @__PURE__ */ new Date();
+			const events = await transaction.select().from(this.config.tables.outboxEvents).where((0, drizzle_orm.or)((0, drizzle_orm.eq)(this.config.tables.outboxEvents.status, outbox_event_bus.EventStatus.CREATED), (0, drizzle_orm.and)((0, drizzle_orm.eq)(this.config.tables.outboxEvents.status, outbox_event_bus.EventStatus.FAILED), (0, drizzle_orm.lt)(this.config.tables.outboxEvents.retryCount, this.config.maxRetries), (0, drizzle_orm.lt)(this.config.tables.outboxEvents.nextRetryAt, now)), (0, drizzle_orm.and)((0, drizzle_orm.eq)(this.config.tables.outboxEvents.status, outbox_event_bus.EventStatus.ACTIVE), (0, drizzle_orm.lt)(this.config.tables.outboxEvents.keepAlive, drizzle_orm.sql`${now.toISOString()}::timestamp - make_interval(secs => ${this.config.tables.outboxEvents.expireInSeconds})`)))).limit(this.config.batchSize).for("update", { skipLocked: true });
+			if (events.length === 0) return;
+			const eventIds = events.map((event) => event.id);
+			await transaction.update(this.config.tables.outboxEvents).set({
+				status: outbox_event_bus.EventStatus.ACTIVE,
+				startedOn: now,
+				keepAlive: now
+			}).where((0, drizzle_orm.inArray)(this.config.tables.outboxEvents.id, eventIds));
+			for (const event of events) try {
+				await handler(event);
+				await transaction.insert(this.config.tables.outboxEventsArchive).values({
+					id: event.id,
+					type: event.type,
+					payload: event.payload,
+					occurredAt: event.occurredAt,
+					status: outbox_event_bus.EventStatus.COMPLETED,
+					retryCount: event.retryCount,
+					createdOn: event.createdOn,
+					startedOn: now,
+					completedOn: /* @__PURE__ */ new Date()
+				});
+				await transaction.delete(this.config.tables.outboxEvents).where((0, drizzle_orm.eq)(this.config.tables.outboxEvents.id, event.id));
+			} catch (error) {
+				const retryCount = event.retryCount + 1;
+				(0, outbox_event_bus.reportEventError)(this.poller.onError, error, event, retryCount, this.config.maxRetries);
+				const delay = this.poller.calculateBackoff(retryCount);
+				await transaction.update(this.config.tables.outboxEvents).set({
+					status: outbox_event_bus.EventStatus.FAILED,
+					retryCount,
+					lastError: (0, outbox_event_bus.formatErrorMessage)(error),
+					nextRetryAt: new Date(Date.now() + delay)
+				}).where((0, drizzle_orm.eq)(this.config.tables.outboxEvents.id, event.id));
+			}
+		});
+	}
+};
+
+//#endregion
+//#region src/transaction-storage.ts
+const drizzleTransactionStorage = new node_async_hooks.AsyncLocalStorage();
+async function withDrizzleTransaction(db, fn) {
+	return db.transaction(async (tx) => {
+		return drizzleTransactionStorage.run(tx, () => fn(tx));
+	});
+}
+function getDrizzleTransaction() {
+	return () => drizzleTransactionStorage.getStore();
+}
+
+//#endregion
+exports.PostgresDrizzleOutbox = PostgresDrizzleOutbox;
+exports.drizzleTransactionStorage = drizzleTransactionStorage;
+exports.getDrizzleTransaction = getDrizzleTransaction;
+exports.withDrizzleTransaction = withDrizzleTransaction;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["PollingService","EventStatus","failedEvent: FailedBusEvent","error: unknown","AsyncLocalStorage"],"sources":["../src/schema.ts","../src/postgres-drizzle-outbox.ts","../src/transaction-storage.ts"],"sourcesContent":["import { integer, jsonb, pgEnum, pgTable, text, timestamp, uuid } from \"drizzle-orm/pg-core\"\n\nexport const outboxStatusEnum = pgEnum(\"outbox_status\", [\n  \"created\",\n  \"active\",\n  \"completed\",\n  \"failed\",\n])\n\nexport const outboxEvents = pgTable(\"outbox_events\", {\n  id: uuid(\"id\").primaryKey(),\n  type: text(\"type\").notNull(),\n  payload: jsonb(\"payload\").notNull(),\n  occurredAt: timestamp(\"occurred_at\").notNull(),\n  status: outboxStatusEnum(\"status\").notNull().default(\"created\"),\n  retryCount: integer(\"retry_count\").notNull().default(0),\n  lastError: text(\"last_error\"),\n  nextRetryAt: timestamp(\"next_retry_at\"),\n  createdOn: timestamp(\"created_on\").notNull().defaultNow(),\n  startedOn: timestamp(\"started_on\"),\n  completedOn: timestamp(\"completed_on\"),\n  keepAlive: timestamp(\"keep_alive\"),\n  expireInSeconds: integer(\"expire_in_seconds\").notNull().default(300),\n})\n\nexport const outboxEventsArchive = pgTable(\"outbox_events_archive\", {\n  id: uuid(\"id\").primaryKey(),\n  type: text(\"type\").notNull(),\n  payload: jsonb(\"payload\").notNull(),\n  occurredAt: timestamp(\"occurred_at\").notNull(),\n  status: outboxStatusEnum(\"status\").notNull(),\n  retryCount: integer(\"retry_count\").notNull(),\n  lastError: text(\"last_error\"),\n  createdOn: timestamp(\"created_on\").notNull(),\n  startedOn: timestamp(\"started_on\"),\n  completedOn: timestamp(\"completed_on\").notNull(),\n})\n","import { and, eq, inArray, lt, or, sql } from \"drizzle-orm\"\nimport type { PostgresJsDatabase } from \"drizzle-orm/postgres-js\"\nimport {\n  type BusEvent,\n  type ErrorHandler,\n  EventStatus,\n  type FailedBusEvent,\n  formatErrorMessage,\n  type IOutbox,\n  type OutboxConfig,\n  PollingService,\n  reportEventError,\n} from \"outbox-event-bus\"\nimport { outboxEvents, outboxEventsArchive } from \"./schema\"\n\nexport interface PostgresDrizzleOutboxConfig extends OutboxConfig {\n  db: PostgresJsDatabase<Record<string, unknown>>\n  getTransaction?: (() => PostgresJsDatabase<Record<string, unknown>> | undefined) | undefined\n  tables?: {\n    outboxEvents: typeof outboxEvents\n    outboxEventsArchive: typeof outboxEventsArchive\n  }\n}\n\nexport class PostgresDrizzleOutbox implements IOutbox<PostgresJsDatabase<Record<string, unknown>>> {\n  private readonly config: Required<PostgresDrizzleOutboxConfig>\n  private readonly poller: PollingService\n\n  constructor(config: PostgresDrizzleOutboxConfig) {\n    this.config = {\n      batchSize: config.batchSize ?? 50,\n      pollIntervalMs: config.pollIntervalMs ?? 1000,\n      maxRetries: config.maxRetries ?? 5,\n      baseBackoffMs: config.baseBackoffMs ?? 1000,\n      processingTimeoutMs: config.processingTimeoutMs ?? 30000,\n      maxErrorBackoffMs: config.maxErrorBackoffMs ?? 30000,\n      db: config.db,\n      getTransaction: config.getTransaction,\n      tables: config.tables ?? {\n        outboxEvents,\n        outboxEventsArchive,\n      },\n    }\n\n    this.poller = new PollingService({\n      pollIntervalMs: this.config.pollIntervalMs,\n      baseBackoffMs: this.config.baseBackoffMs,\n      maxErrorBackoffMs: this.config.maxErrorBackoffMs,\n      processBatch: (handler) => this.processBatch(handler),\n    })\n  }\n\n  async publish(\n    events: BusEvent[],\n    transaction?: PostgresJsDatabase<Record<string, unknown>>\n  ): Promise<void> {\n    const executor = transaction ?? this.config.getTransaction?.() ?? this.config.db\n\n    await executor.insert(this.config.tables.outboxEvents).values(\n      events.map((event) => ({\n        id: event.id,\n        type: event.type,\n        payload: event.payload,\n        occurredAt: event.occurredAt,\n        status: EventStatus.CREATED,\n      }))\n    )\n  }\n\n  async getFailedEvents(): Promise<FailedBusEvent[]> {\n    const events = await this.config.db\n      .select()\n      .from(this.config.tables.outboxEvents)\n      .where(eq(this.config.tables.outboxEvents.status, EventStatus.FAILED))\n      .orderBy(sql`${this.config.tables.outboxEvents.occurredAt} DESC`)\n      .limit(100)\n\n    return events.map((event) => {\n      const failedEvent: FailedBusEvent = {\n        id: event.id,\n        type: event.type,\n        payload: event.payload as any,\n        occurredAt: event.occurredAt,\n        retryCount: event.retryCount,\n      }\n      if (event.lastError) failedEvent.error = event.lastError\n      if (event.startedOn) failedEvent.lastAttemptAt = event.startedOn\n      return failedEvent\n    })\n  }\n\n  async retryEvents(eventIds: string[]): Promise<void> {\n    await this.config.db\n      .update(this.config.tables.outboxEvents)\n      .set({\n        status: EventStatus.CREATED,\n        retryCount: 0,\n        nextRetryAt: null,\n        lastError: null,\n      })\n      .where(inArray(this.config.tables.outboxEvents.id, eventIds))\n  }\n\n  start(handler: (event: BusEvent) => Promise<void>, onError: ErrorHandler): void {\n    this.poller.start(handler, onError)\n  }\n\n  async stop(): Promise<void> {\n    await this.poller.stop()\n  }\n\n  private async processBatch(handler: (event: BusEvent) => Promise<void>) {\n    await this.config.db.transaction(async (transaction) => {\n      const now = new Date()\n\n      // Select events that are:\n      // 1. New (status = created)\n      // 2. Failed but can be retried (retry count < max AND retry time has passed)\n      // 3. Active but stuck/timed out (keepAlive is older than now - expireInSeconds)\n      const events = await transaction\n        .select()\n        .from(this.config.tables.outboxEvents)\n        .where(\n          or(\n            eq(this.config.tables.outboxEvents.status, EventStatus.CREATED),\n            and(\n              eq(this.config.tables.outboxEvents.status, EventStatus.FAILED),\n              lt(this.config.tables.outboxEvents.retryCount, this.config.maxRetries),\n              lt(this.config.tables.outboxEvents.nextRetryAt, now)\n            ),\n            and(\n              eq(this.config.tables.outboxEvents.status, EventStatus.ACTIVE),\n              // Check if event is stuck: keepAlive is older than (now - expireInSeconds)\n              // This uses PostgreSQL's make_interval to subtract expireInSeconds from current timestamp\n              lt(\n                this.config.tables.outboxEvents.keepAlive,\n                sql`${now.toISOString()}::timestamp - make_interval(secs => ${this.config.tables.outboxEvents.expireInSeconds})`\n              )\n            )\n          )\n        )\n        .limit(this.config.batchSize)\n        .for(\"update\", { skipLocked: true })\n\n      if (events.length === 0) return\n\n      const eventIds = events.map((event) => event.id)\n\n      await transaction\n        .update(this.config.tables.outboxEvents)\n        .set({\n          status: EventStatus.ACTIVE,\n          startedOn: now,\n          keepAlive: now,\n        })\n        .where(inArray(this.config.tables.outboxEvents.id, eventIds))\n\n      for (const event of events) {\n        try {\n          await handler(event)\n          // Archive successful event immediately\n          await transaction.insert(this.config.tables.outboxEventsArchive).values({\n            id: event.id,\n            type: event.type,\n            payload: event.payload,\n            occurredAt: event.occurredAt,\n            status: EventStatus.COMPLETED,\n            retryCount: event.retryCount,\n            createdOn: event.createdOn,\n            startedOn: now,\n            completedOn: new Date(),\n          })\n          await transaction\n            .delete(this.config.tables.outboxEvents)\n            .where(eq(this.config.tables.outboxEvents.id, event.id))\n        } catch (error: unknown) {\n          const retryCount = event.retryCount + 1\n          reportEventError(this.poller.onError, error, event, retryCount, this.config.maxRetries)\n\n          // Mark this specific event as failed\n          const delay = this.poller.calculateBackoff(retryCount)\n          await transaction\n            .update(this.config.tables.outboxEvents)\n            .set({\n              status: EventStatus.FAILED,\n              retryCount,\n              lastError: formatErrorMessage(error),\n              nextRetryAt: new Date(Date.now() + delay),\n            })\n            .where(eq(this.config.tables.outboxEvents.id, event.id))\n        }\n      }\n    })\n  }\n}\n","import { AsyncLocalStorage } from \"node:async_hooks\"\nimport type { PostgresJsDatabase } from \"drizzle-orm/postgres-js\"\n\nexport const drizzleTransactionStorage = new AsyncLocalStorage<\n  PostgresJsDatabase<Record<string, unknown>>\n>()\n\nexport async function withDrizzleTransaction<T>(\n  db: PostgresJsDatabase<Record<string, unknown>>,\n  fn: (tx: PostgresJsDatabase<Record<string, unknown>>) => Promise<T>\n): Promise<T> {\n  return db.transaction(async (tx) => {\n    return drizzleTransactionStorage.run(tx, () => fn(tx))\n  })\n}\n\nexport function getDrizzleTransaction(): () =>\n  | PostgresJsDatabase<Record<string, unknown>>\n  | undefined {\n  return () => drizzleTransactionStorage.getStore()\n}\n"],"mappings":"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"}