How cap-js-community/event-queue works
1. This repository is a CAP Node.js plugin/framework for asynchronous event processing. The entry point is cds-plugin.js, which makes the package auto-attach to CAP applications. The public API lives in src/index.js and is backed by the core runtime modules under src/.
2. The central architectural boundary is the persisted event queue in the database. The CDS model in db/Event.cds, db/Lock.cds, and db/index.cds defines the queue and coordination tables that CAP apps deploy into their schema. The queue is the system of record for events until they are processed or cleaned up.
3. Event publication flows through src/publishEvent.js and src/dbHandler.js. Application code or CAP handlers enqueue work into the DB, where it becomes durable and visible to workers. Configuration is resolved through src/config.js, src/constants.js, and helper utilities in src/shared/.
4. Event consumption is handled by src/processEventQueue.js, with the processor abstraction in src/EventQueueProcessorBase.js. These modules implement the event execution lifecycle, including status handling, retry/error wrapping via src/EventQueueError.js, and transaction-aware processing.
5. Horizontal scaling and concurrency control are a major design point. src/shared/distributedLock.js, src/runner/runner.js, src/runner/openEvents.js, and src/runner/runnerHelper.js coordinate multiple application instances so only the right instance processes a given slice of the queue. src/shared/WorkerQueue.js and src/shared/SetIntervalDriftSafe.js support controlled execution and periodic scheduling.
6. Redis is used as an accelerator and coordination channel. The modules in src/redis/ and src/shared/redis/ implement pub/sub and client management so instances can react quickly to newly published events instead of relying only on polling. This is a low-latency path layered on top of the durable DB queue.
7. Periodic work is a first-class feature rather than an external cron dependency. src/periodicEvents.js and src/shared/eventScheduler.js drive scheduled execution, while the test suite includes dedicated periodic-event scenarios. The scheduler is integrated into the same queue/worker model as ordinary events.
8. There is explicit support for CAP outbox integration. src/outbox/eventQueueAsOutbox.js and src/outbox/EventQueueGenericOutboxHandler.js adapt the event queue to CAP’s outbox semantics, letting existing CAP services publish through the queue without changing their business code. This is a distinct integration boundary from the core queue engine.
9. Housekeeping and operational concerns are separated from the hot path. src/housekeeping/EventQueueDeleteEvents.js removes old queue entries, and src/shared/eventQueueStats.js plus src/shared/PerformanceTracer.js capture runtime health and performance data. src/shared/openTelemetry.js indicates optional observability hooks.
10. CAP service integration is demonstrated in srv/ and example-cap-server/. The admin service in srv/service/admin-service.js exposes management functionality, while the example server shows a real consumer/producer setup with service facades, handlers, and CDS service definitions. This example is part of the repo’s architecture documentation by code.
11. The project is heavily test-driven across unit, integration, and end-to-end layers. test/ covers core helpers and queue behavior, while test-integration/ exercises Redis, HANA deployment, runner behavior, transaction handling, and periodic events. The test/asset/outboxProject fixture is especially useful for understanding how the plugin behaves inside a real CAP app.
12. In diagram terms, the main flow is: CAP app or outbox producer publishes an event into the DB queue; scheduler/runner instances discover open events; distributed locking and Redis coordination prevent duplicate work; a worker executes the handler inside CAP-managed transaction boundaries; housekeeping later removes completed records. The main external dependencies that shape the architecture are CAP Node.js, a relational database, and optionally Redis for cross-instance coordination.
Main entry points: processEventQueue.js Process queue · dbHandler.js DB handler · eventQueueAsOutbox.js Outbox adapter · publishEvent.js Publish
Components 23
Package entry
Auto-attachment and public API entry points
- cds-plugin · Auto-attaches the package to CAP applications
cds-plugin.js - Public API · Exports the package API and runtime wiring
src/index.js
Core runtime
Publishing, queue processing, scheduling, and lifecycle orchestration
- Init · Initializes plugin state and runtime wiring
src/initialize.js - Config · Resolves runtime configuration and constants
src/config.js - Publish · Turns application events into durable queue records
src/publishEvent.js - DB handler · Writes and reads queue state through CAP persistence
src/dbHandler.js - Process queue · Drives event consumption and execution lifecycle
src/processEventQueue.js - Processor base · Shared processor abstraction for queue handlers
src/EventQueueProcessorBase.js - Periodic events · Schedules recurring work onto the same queue model
src/periodicEvents.js
Persistence
Database schema and durable queue tables
- Event schema · Defines the persisted event queue table
db/Event.cds - Lock schema · Defines coordination and locking tables
db/Lock.cds - DB index · Aggregates the queue schema for deployment
db/index.cds
Coordination
Locking, runners, and Redis-assisted cross-instance coordination
- Runner · Coordinates worker startup and queue polling
src/runner/runner.js - Open events · Finds eligible events and hands them to workers
src/runner/openEvents.js - Distributed lock · Prevents duplicate processing across instances
src/shared/distributedLock.js - Redis pub · Publishes low-latency event notifications
src/redis/redisPub.js - Redis sub · Receives notifications and wakes polling workers
src/redis/redisSub.js - Redis client · Shared Redis client and connection management
src/shared/redis/index.js
Integrations
CAP outbox and service-facing adapters
- Outbox adapter · Adapts the queue to CAP outbox semantics
src/outbox/eventQueueAsOutbox.js - Outbox handler · Implements generic outbox integration behavior
src/outbox/EventQueueGenericOutboxHandler.js - Admin service · Exposes management and administration endpoints
srv/service/admin-service.js - Example app · Shows CAP service usage with queue-backed handlers
example-cap-server/srv/handler/process-service.js
Ops
Housekeeping and runtime telemetry
- Housekeeping · Deletes old queue records after processing
src/housekeeping/EventQueueDeleteEvents.js
Connections 22
- cds-plugin → Public API: loads · The plugin entry wires the public API into CAP
- Public API → Init: initializes · Public API bootstraps runtime setup
- Init → Config: reads · Initialization resolves configuration
- Publish → DB handler: persists · Published events are written through the DB handler
- DB handler → Event schema: stores · Event rows are stored in the queue table
- DB handler → Lock schema: coordinates · Lock state is stored alongside queue data
- DB index → Event schema: includes · Schema aggregation includes the event table
- DB index → Lock schema: includes · Schema aggregation includes the lock table
- Process queue → Processor base: executes via · Queue processing is built on the processor base
- Process queue → Open events: discovers · Processing asks runner logic for open events
- Open events → Distributed lock: claims · Open-event selection is protected by distributed locking
- Runner → Open events: orchestrates · The runner coordinates event discovery
- Runner → Redis pub: publishes · Runner path can react to Redis notifications
- Redis sub → Redis client: uses · Subscriber relies on shared Redis client management
- Redis pub → Redis client: uses · Publisher relies on shared Redis client management
- Periodic events → Process queue: enqueues · Periodic work is processed by the same queue engine
- Outbox adapter → Outbox handler: implements · Outbox adapter is backed by the generic handler
- Outbox adapter → Publish: publishes through · Outbox integration routes work into event publication
- Housekeeping → Event schema: cleans · Housekeeping deletes old event rows
- Admin service → Process queue: manages · Admin service observes or manages queue processing
- Example app → Outbox adapter: demonstrates · Example app shows outbox-style integration
- Example app → Publish: produces · Example services publish events into the queue