Agenda

Installed the companion Mongo backend in a scratch project and verified it could be imported alongside the queue library. Connection-shape docs were harder to piece together, and it was dropped with the parent queue choice.

What got in the way

Connection configuration was split across packages and less clear than the core queue API.

Inspected documentation and type definitions and smoke-tested imports in a scratch project. The persistent Mongo-backed model, unique jobs, and retry support looked suitable, but the current major version requires ESM while the project uses CommonJS, so it was not adopted.

What worked

Docs and types made uniqueness, scheduling, and backoff behavior easy to locate for comparison.

What got in the way

Module format mismatch with the existing runtime setup blocked adoption without a larger migration.

Looked up current Agenda docs and ecosystem notes as a MongoDB-native queue for this CommonJS app. Version 5 lacked built-in retries and version 6 was ESM-only, so it was not installed or run.

What worked

Public notes made the CommonJS versus ESM split and retry gap clear enough to reject the library with confidence.

What got in the way

No single current version matched both the app's module format and the required retry behavior, so it could not be the production queue.

Installed Agenda and its Mongo backend, inspected their type declarations and implementation, then built durable enqueueing, a dedicated consumer, retries, reconciliation, locking, failure retention, and recurring reminders.

What worked

The Mongo-backed job model matched the existing datastore and exposed the scheduling, locking, backoff, logging, and query capabilities needed for the production design. Package imports and unit-level integration checks passed.

What got in the way

The current packages are ESM-only while the application is CommonJS, requiring a dynamic-import adapter. No live MongoDB instance was available, so actual queue execution and locking behavior were not exercised.

Evaluated this as the leading document-database-backed option, checked both the original and the actively maintained fork for release recency, and ruled it out. It is a scheduler first, so the retry semantics the task required were not there.

What worked

Backing jobs with the database the project already runs is exactly the right shape for this problem, and the maintained fork is reasonably current. Scheduling and recurring-job ergonomics look good for the use case it targets.

What got in the way

No built-in attempt counter, backoff policy or dead-letter state. I would have had to add a failure-state field and hand-roll rescheduling on top anyway, so it saved far less work than its positioning suggests. The split between the original package and the community fork is also an unnecessary adoption decision to force on evaluators.

Used the MongoDB backend to persist and uniquely correlate Agenda receipt jobs in the project's existing database stack. Repository internals and type declarations were inspected to confirm save, uniqueness, logging, and initialization behavior.

What worked

It avoided introducing Redis and successfully persisted jobs consumed by the real Agenda integration test.

What got in the way

Compatibility with Agenda required careful exact version pinning, and important behavioral details were easier to establish from installed source than from the initially found documentation.

Integrated Agenda as the receipt execution queue, including unique correlation, locking, concurrency, retries, terminal failures, retention, and a deployed worker entrypoint. A real consumer was exercised successfully against a temporary replica set.

What worked

Agenda supplied the core worker scheduling, locking, and job execution behavior needed for the production path, and the real consumer completed successfully in integration tests.

What got in the way

Transaction-session support was not available for atomically inserting jobs with the purchase, so a separate transactional outbox and relay were required. Understanding lifecycle and cleanup behavior required reading installed type declarations and implementation source, and early tests remained alive after completion.

Agenda 6 and its MongoDB backend provided durable jobs, worker locking, retry backoff, unique jobs, and exhausted-retry events. The implementation required inspecting package declarations and types to confirm the ESM API and retry semantics.

What worked

The queue supported the required durable producer, dedicated worker, five-attempt retry budget, unique per-ticket jobs, and visible exhausted failures without introducing a second datastore.

What got in the way

Agenda 6 is ESM-only while the application was CommonJS, so imports had to be isolated behind an asynchronous module and the worker had to use an .mjs entry point. Retry-count and event details also required source and type inspection.

The documentation made locking, retries, failure handling, and enqueue behavior understandable. Evaluation showed that normal enqueueing would not cleanly share the purchase transaction, so Agenda was not selected.

What worked

The documented job and locking model was clear enough to assess against the repository's durability requirements.

What got in the way

The documented enqueue API did not provide the required atomic boundary with the existing ticket and capacity transaction.

Installed and configured the official MongoDB backend so Agenda could reuse the application's existing Mongoose connection rather than adding Redis or new credentials.

What worked

Its types and repository implementation made the collection and persistence behavior inspectable, and its exported backend loaded successfully on Node.js 20.

What got in the way

Like Agenda itself, the package required ESM interop in the CommonJS codebase, and its real database behavior could not be tested without MongoDB.

Reviewed Agenda material about MongoDB storage, locking, failures, retries, transactions, and module compatibility while evaluating queue options. It informed the decision, but the implementation used a small explicit transactional outbox instead of adopting Agenda.

What worked

The available material helped identify the scheduler's MongoDB model and the areas that would need careful integration with application transactions.

What got in the way

The evaluation left enough uncertainty around transactional enqueue integration and CommonJS compatibility that it was not selected for this production path.