Agent usage guide
This guide covers published @nestarc/outbox 0.4.1. Start with npm ls @nestarc/outbox @nestjs/core @nestjs/schedule @prisma/client in the consuming application. Repository main can contain fixes that are not in the installed package; compare against the 0.4.1 README, usage reference, and tagged source.
Build a working integration
- Use PostgreSQL and the supported Node/Nest/Prisma combination from installation. PostgreSQL 16 is the automated baseline; an older minimum has not been verified. Prisma 7's PostgreSQL adapter needs
pgeven when notifications are disabled. - Apply the package's complete fresh-install SQL before starting a new app. A current 0.3.0 schema needs no additional SQL for 0.4.1. For a 0.1/0.2 upgrade, stop all old pollers and apply
upgrade-to-current.sql; never overlap 0.2 workers with 0.3/0.4 workers. - Register an injectable Prisma provider. Use
forRootAsync()with exporting dependency modules when the transport or tenant provider has injected dependencies. PuttransportandtenantProviderat the top level of the async registration. - Write business data and call
OutboxEmitter.emit(tx, event, options)inside the same Prisma transaction. A call using an independent client does not provide the same atomicity. - Register local decorated handlers as Nest providers, or select
delivery.mode: 'publisher'with anOutboxPublisher. Preserve the event ID, payload, and metadata through the broker; consumers must deduplicate side effects. - Keep periodic polling enabled; 0.4 rejects
polling.enabled: false. An API-only process can registerOutboxEmitterdirectly withoutOutboxModule. With Jobs 0.4.2, use one application-owned signal handler that awaitsOutboxPoller.stop({ timeoutMs: 30_000 })beforeapp.close(). OnOUTBOX_SHUTDOWN_INCOMPLETE, keep Jobs and Prisma open and retry the stop after work settles; timeout does not cancel callbacks. Do not also enable Nest automatic signal-close for that process. - Verify a committed event reaches
SENT, a rolled-back transaction leaves neither business data nor an event, and a failed callback retries before reachingFAILED.SENTacknowledges local handlers or the publisher, not downstream completion.
Import runtime values and types from @nestarc/outbox. The supported SQL exports are @nestarc/outbox/src/sql/create-outbox-table.sql and @nestarc/outbox/src/sql/upgrade-to-current.sql; do not import internal dist/** paths. For full signatures, use the installed .d.ts files and published API reference.
0.4 migration and operating boundaries
| Area | Consumer guidance |
|---|---|
| Coordinated shutdown (0.4.1) | OutboxPoller, OutboxStopOptions, OutboxShutdownError, and OUTBOX_SHUTDOWN_INCOMPLETE are public root exports. Stop is permanent and concurrent/repeated calls are safe. The automatic hook now rejects incomplete drain instead of logging remaining work and returning after its default 30-second deadline. |
| Required polling | polling.enabled: false fails module initialization with OutboxConfigurationError / OUTBOX_INVALID_CONFIGURATION, even with working LISTEN/NOTIFY. Notifications reduce latency; polling discovers backlog, due retries, and expired claims. |
| Admin cursor pagination | listPage() now returns v2 cursors preserving PostgreSQL microseconds. Discard saved v1 cursors and restart from the first page; unsupported cursors raise OUTBOX_INVALID_CURSOR. Pass nextCursor unchanged and keep filters stable; public Date fields cannot reconstruct it. |
| Configuration checks | Setup validates tenant policy/provider shapes, observability callbacks, and notification options. This does not establish external connectivity or guarantee callback behavior. |
| Database schema | Required schema remains 0.3.0. An existing current 0.3.0 schema needs no additional migration; 0.1/0.2 databases still need the unified upgrade. |
| Ordering and uniqueness | Delivery is at-least-once and has no global, aggregate, partition, or batch FIFO guarantee. partitionKey controls routing; idempotencyKey is metadata and does not create an outbox uniqueness constraint. |
| Tenant administration | Authenticate and authorize the tenant before calling OutboxTenantAdminService.forTenant(). OutboxOperatorService is privileged and global. |
The 0.3.0 cursor precision and notification-only startup behavior no longer describe the current release. Applications remaining on that version should use the historical 0.3.0 README.
Reference and verification paths
- Installation, SQL, shutdown, and complete provider registration
- Local handlers and callback behavior
- Broker publishers with preserved event identities
- Delivery lifecycle and guarantees
- Complete quick-start application and run instructions
- Version-pinned consumer fixtures
- Fixture runner and database requirements
- Packaged documentation map
The quick start ships complete imports, providers, models, and a consumer receipt that commits atomically with a database side effect. It uses a disposable PostgreSQL database and verifies SENT plus duplicate replay without sending email or contacting a broker. The packed fixture harness exercises installed-package examples with and without optional pg. Follow its database setup instructions; recording broker/email doubles do not verify real acknowledgements or external side-effect deduplication.