feat: add middleware/hooks system for event processing (Vibe Kanban)

[jtomaszewski]

Summary

Adds a middleware/hook system to the outbox event processor that allows intercepting event processing for:

• Error reporting (e.g., Sentry)
• Logging (start/end with timing)
• Tracing (OpenTelemetry spans)

Changes

New Middleware Interface

The middleware system supports two approaches:

1. Class-based middlewares (supports NestJS dependency injection):

@Injectable()
class SentryOutboxMiddleware implements OutboxMiddleware {
  constructor(private sentry: SentryService) {}

  async onError(ctx: OutboxEventContext, error: Error) {
    this.sentry.captureException(error, { extra: ctx });
  }
}

OutboxModule.registerAsync({
  middlewares: [SentryOutboxMiddleware],
  // ...
})

2. Function-based hooks (simpler use cases):

OutboxModule.registerAsync({
  hooks: {
    beforeProcess: (ctx) => console.log(`Processing ${ctx.eventName}`),
    afterProcess: (ctx, result) => console.log(`Done in ${result.durationMs}ms`),
    onError: (ctx, error) => captureException(error),
  },
  // ...
})

Context Provided to Hooks

interface OutboxEventContext {
  eventName: string;      // Name of the event
  eventPayload: unknown;  // Event payload data
  eventId: number;        // Database ID of the event
  listenerName: string;   // Name of the listener being executed
}

interface OutboxListenerResult {
  success: boolean;       // Whether processing succeeded
  error?: Error;          // Error if failed
  durationMs: number;     // Execution time in milliseconds
}

Hook Lifecycle

1. beforeProcess - Called before each listener processes the event
2. Listener executes
3. afterProcess - Called after processing (success or failure) with timing info
4. onError - Called only when an error occurs (before afterProcess)

Implementation Details

• Middlewares are instantiated via NestJS ModuleRef.create() enabling full DI support
• Function-based hooks are wrapped in a HooksMiddlewareAdapter class internally
• Middleware errors are caught and logged but don't break event processing
• Both middlewares and hooks can be used together (middlewares run first)

Files Changed

• src/middleware/outbox-middleware.interface.ts - New middleware interfaces and types
• src/outbox.module-definition.ts - Added middlewares and hooks config options
• src/outbox.module.ts - Added middleware instantiation and adapter
• src/processor/outbox-event.processor.ts - Added hook invocations with timing
• src/index.ts - Exported new middleware types
• src/test/unit/outbox-event-processor.spec.ts - Added 5 comprehensive tests

---

This PR was written using Vibe Kanban

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/fullstackhouse/nestjs-outbox/@fullstackhouse/nestjs-outbox@27

npm i https://pkg.pr.new/fullstackhouse/nestjs-outbox/@fullstackhouse/nestjs-outbox-mikro-orm-driver@27

npm i https://pkg.pr.new/fullstackhouse/nestjs-outbox/@fullstackhouse/nestjs-outbox-typeorm-driver@27

commit: 11a756e