Event Callbacks improvements (#453)

* docu and triggerEvent

* fixes

* linter

* fix and add more tests

* docu update

* wip

* fix tests

* finish up

* changelog and fix tests

* fix tests

---------

Co-authored-by: Max Gruenfelder <maximilian.gruenfelder@scheer-group.com>

Author: soccermax

CHANGELOG.md

@@ -5,18 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-## v2.1.0 - 2025-03-XX
+## v2.1.0 - 2025-04-06
 
 ### Added
 
-- [CAP Queue] Add support for defining successor and failed events of event handlers. See documentation for how to use it.
+- [CAP Queue] Add support for event chaining: register `#succeeded` and `#failed` successor handlers that are automatically triggered based on the outcome of an event handler. See [documentation](https://cap-js-community.github.io/event-queue/use-as-cap-outbox/#event-chaining).
+- [CAP Queue] Add `#done` unconditional successor — fires after every event regardless of success or failure, analogous to a `finally` block. Useful for cleanup that must always run (releasing locks, audit events, etc.).
+- [CAP Queue] Successor handlers (`#succeeded`, `#failed`, `#done`) can be configured independently in the `events` section of the service's `queued` configuration, including event-specific variants (e.g. `orderCreated/#succeeded`).
+- [Telemetry] Add opt-in event queue metrics (`collectEventQueueMetrics`). When enabled together with Redis and an OpenTelemetry MeterProvider, the module publishes `cap.event_queue.jobs.pending`, `cap.event_queue.jobs.in_progress`, and `cap.event_queue.stats.refresh_age` as Observable Gauges, broken down by namespace. See [documentation](https://cap-js-community.github.io/event-queue/telemetry/).
 
 ## v2.0.5 - 2025-03-10
 
 ### Added
 
 - [CAP Queue] Allow to propagate cds.context properties (e.g. features). This can be configured per event (`cds.env.requires[<SERVICE>].queued.propagateContextProperties = ["features"]`)
-- [Telemetry] Add opt-in event queue metrics (`collectEventQueueMetrics`). When enabled together with Redis and an OpenTelemetry MeterProvider, the module publishes `cap.event_queue.jobs.pending`, `cap.event_queue.jobs.in_progress`, and `cap.event_queue.stats.refresh_age` as Observable Gauges, broken down by namespace. See [documentation](https://cap-js-community.github.io/event-queue/telemetry/).
 
 ### Fixed
 

docs/setup/index.md

@@ -77,6 +77,7 @@ The table includes the parameter name, a description of its purpose, and the def
 | cleanupLocksAndEventsForDev          | Deletes all semantic locks and sets all events that are in progress to error during server start. This is used to clean up leftovers from server crashes or restarts during processing.                                                                                                                                                                                                                                                     | true           | no                        |
 | insertEventsBeforeCommit             | If enabled, this feature allows events (including those for queued services) to be inserted in bulk using the before commit handler. This is performed to improve performance by mass inserting events instead of single insert operations. This can be disabled by the parameter `skipInsertEventsBeforeCommit` in the function publishEvent.                                                                                              | true           | yes                       |
 | enableTelemetry                      | If enabled, OpenTelemetry traces for all event-queue activities are written. An OpenTelemetry exporter must be configured.                                                                                                                                                                                                                                                                                                                  | true           | yes                       |
+| collectEventQueueMetrics             | If enabled, publishes `cap.event_queue.jobs.pending`, `cap.event_queue.jobs.in_progress`, and `cap.event_queue.stats.refresh_age` as OpenTelemetry Observable Gauges. Requires `enableTelemetry: true`, Redis, and an OpenTelemetry MeterProvider. See [documentation](https://cap-js-community.github.io/event-queue/telemetry/).                                                                                                          | false          | no                        |
 | cronTimezone                         | Determines whether to apply the central `cronTimezone` setting for scheduling events. If set to `true` and the property `utc` is not enabled for the given event, it will use the defined `cronTimezone`. If set to `false`, the event will use UTC or the server's local time, based on the `utc` setting.                                                                                                                                 | null           | yes                       |
 | randomOffsetPeriodicEvents           | Specifies the default maximum random offset (in seconds) applied to all periodic events to help stagger their start times and reduce simultaneous execution spikes. This setting is especially useful in multi-tenant environments where many events may be triggered at the same time. The actual offset for each event will be a random number between `0` and this value. Can be overridden per event using the `randomOffset` property. | null           | yes                       |
 | disableRedis                         | Whether or not to disable Redis.                                                                                                                                                                                                                                                                                                                                                                                                            | false          | no                        |

docs/telemetry/index.md

@@ -148,12 +148,14 @@ Or via `cds.env` (e.g. in `package.json`):
 
 The full set of conditions required for metrics to be active:
 
-| Condition                  | Required value | Notes                                                |
-| -------------------------- | -------------- | ---------------------------------------------------- |
-| `collectEventQueueMetrics` | `true`         | Master switch; default `false`                       |
-| `enableTelemetry`          | `true`         | Default `true`; global telemetry kill-switch         |
-| Redis enabled              | yes            | Stats are stored in Redis hashes                     |
-| OpenTelemetry metrics SDK  | present        | `@opentelemetry/api` with a configured MeterProvider |
+| Condition                  | Required value | Notes                                                                                        |
+| -------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
+| `collectEventQueueMetrics` | `true`         | Master switch; default `false`                                                               |
+| `enableTelemetry`          | `true`         | Default `true`; global telemetry kill-switch                                                 |
+| Redis enabled              | yes            | Stats are stored in Redis hashes                                                             |
+| `registerAsEventProcessor` | `true`         | Metrics are only initialised on instances that process events                                |
+| CF instance index          | `0`            | Only the first application instance registers gauges to avoid duplicate metric registrations |
+| OpenTelemetry metrics SDK  | present        | `@opentelemetry/api` with a configured MeterProvider                                         |
 
 If any condition is not met, `initMetrics()` returns immediately and no gauges are registered.
 

docs/use-as-cap-outbox/index.md

@@ -409,3 +409,207 @@ this.on("myBatchEvent", (req) => {
   }));
 });
 ```
+
+## Event Chaining
+
+The event-queue supports chaining event handlers based on outcome. When a handler completes, the event-queue
+automatically publishes designated **successor events** — allowing you to model multi-step asynchronous workflows
+with clear separation of concerns.
+
+### How It Works
+
+Register successor handlers using the special suffixes `#succeeded`, `#failed`, and `#done`:
+
+- **`<event>/#succeeded`** — triggered when the handler for `<event>` returns `EventProcessingStatus.Done`
+- **`<event>/#failed`** — triggered when the handler returns `EventProcessingStatus.Error` or throws
+- **`<event>/#done`** — triggered unconditionally after `<event>` completes, regardless of outcome (analogous to `finally`)
+
+You can also register **generic** successor handlers (`#succeeded` / `#failed` / `#done`) that apply to every event
+in the service that does not have a dedicated successor.
+
+```javascript
+class MyService extends cds.Service {
+  async init() {
+    await super.init();
+
+    // Primary handler
+    this.on("orderCreated", async (req) => {
+      // ... business logic
+      return EventProcessingStatus.Done;
+    });
+
+    // Runs on success — event-specific
+    this.on("orderCreated/#succeeded", async (req) => {
+      // req.eventQueue.triggerEvent is available here (see below)
+    });
+
+    // Runs on failure — event-specific
+    this.on("orderCreated/#failed", async (req) => {
+      // req.data.error contains the serialised error message
+    });
+
+    // Runs unconditionally — event-specific
+    this.on("orderCreated/#done", async (req) => {
+      // always runs; req.data.error is set when the parent failed
+    });
+
+    // Generic fallbacks — run for any event without a dedicated handler
+    this.on("#succeeded", async (req) => {
+      /* ... */
+    });
+    this.on("#failed", async (req) => {
+      /* ... */
+    });
+    this.on("#done", async (req) => {
+      /* ... */
+    });
+  }
+}
+```
+
+### Passing Data to the Successor
+
+Return a `nextData` property from the primary handler to forward arbitrary data to the successor's `req.data`:
+
+```javascript
+this.on("orderCreated", async (req) => {
+  const orderId = await createOrder(req.data);
+  return {
+    status: EventProcessingStatus.Done,
+    nextData: { orderId }, // available as req.data.orderId in the successor
+  };
+});
+```
+
+`nextData` is forwarded to all active successors (`#succeeded`, `#failed`, `#done`). For `#done` this is useful when cleanup logic needs to act on data produced by the primary handler.
+
+### Accessing the Trigger Event Context (`req.eventQueue.triggerEvent`)
+
+When a successor handler is invoked, `req.eventQueue.triggerEvent` is populated with context from the parent event.
+This gives the successor full visibility into what happened in the previous step.
+
+| Field                 | Type   | Description                                                                        |
+| --------------------- | ------ | ---------------------------------------------------------------------------------- |
+| `triggerEventResult`  | any    | The raw return value of the parent handler (e.g. `{ status: 2, nextData: {...} }`) |
+| `ID`                  | string | UUID of the parent queue entry                                                     |
+| `status`              | number | Status of the parent queue entry at processing time                                |
+| `payload`             | any    | Payload of the parent queue entry                                                  |
+| `referenceEntity`     | string | Reference entity of the parent event (if set)                                      |
+| `referenceEntityKey`  | string | Reference entity key of the parent event (if set)                                  |
+| `lastAttempTimestamp` | string | Timestamp of the last processing attempt of the parent event                       |
+
+`req.eventQueue.triggerEvent` is set in **`#succeeded`**, **`#failed`**, and **`#done`** handlers, but only when the
+event was processed as a single entry (no clustering). When the parent handler **threw an exception**,
+`triggerEventResult` will be `undefined` — the queue entry fields (`ID`, `status`, `payload`, etc.) are still present.
+
+```javascript
+this.on("orderCreated/#succeeded", async (req) => {
+  const { triggerEventResult, ID } = req.eventQueue.triggerEvent;
+
+  // triggerEventResult is exactly what the parent handler returned
+  console.log(triggerEventResult);
+  // → { status: 2, nextData: { orderId: "..." } }
+
+  // ID is the UUID of the parent queue entry
+  console.log(ID); // → "3f2e1a..."
+});
+```
+
+### Failure Handling and Error Propagation
+
+When a primary handler throws or returns `EventProcessingStatus.Error`, the `#failed` and `#done` successors both
+receive the serialised error message in `req.data.error`:
+
+```javascript
+this.on("orderCreated/#failed", async (req) => {
+  console.log(req.data.error); // → "Error: Payment gateway timeout"
+  // compensate, notify, etc.
+  return EventProcessingStatus.Done;
+});
+```
+
+### Unconditional Follow-up (`#done`)
+
+The `#done` handler fires after every event, regardless of whether the primary handler succeeded, failed, or threw.
+It is the equivalent of a `finally` block and is intended for cleanup that must always run:
+
+- Releasing locks or counters
+- Emitting audit events
+- Notifying monitoring systems
+
+`req.data.error` is populated when the parent failed (identical to `#failed`). `req.eventQueue.triggerEvent` is
+available under the same rules as `#succeeded` and `#failed` — use `triggerEventResult.status` to distinguish
+outcomes, or check `triggerEventResult === undefined` to detect an unhandled exception.
+
+Both a specific handler (`<event>/#done`) and a generic handler (`#done`) are supported. The specific handler takes
+priority over the generic one.
+
+### Stopping the Chain
+
+`#failed` and `#done` are always terminal — the event-queue will **not** trigger any further successors after them,
+even if handlers are registered.
+
+`#succeeded` is not fully terminal: if a `#succeeded` handler returns `EventProcessingStatus.Error`, the
+event-queue will trigger `#failed` for that event (the chain continues on the failure path). However, `#succeeded`
+never triggers `#done` a second time.
+
+### Service-Specific vs. Generic Handlers
+
+| Pattern              | Applies to                            |
+| -------------------- | ------------------------------------- |
+| `<event>/#succeeded` | Only `<event>`                        |
+| `<event>/#failed`    | Only `<event>`                        |
+| `<event>/#done`      | Only `<event>`                        |
+| `#succeeded`         | All events without a specific handler |
+| `#failed`            | All events without a specific handler |
+| `#done`              | All events without a specific handler |
+
+Event-specific handlers take priority over generic ones.
+
+### Configuring Successor Handlers
+
+Successor handlers (`#succeeded`, `#failed`, `#done`) can be configured independently in the `events` section of the
+service's `queued` configuration, using the same keys as the handler names.
+
+**Generic successor config** — applies to all handlers of that type across the service:
+
+```json
+{
+  "cds": {
+    "requires": {
+      "my-service": {
+        "queued": {
+          "kind": "persistent-queue",
+          "events": {
+            "#succeeded": { "propagateHeaders": ["x-correlation-id"] },
+            "#failed": { "retryAttempts": 0 },
+            "#done": { "propagateHeaders": ["x-correlation-id"] }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Event-specific successor config** — applies only to the successor of a particular action:
+
+```json
+{
+  "cds": {
+    "requires": {
+      "my-service": {
+        "queued": {
+          "kind": "persistent-queue",
+          "events": {
+            "orderCreated/#succeeded": { "propagateHeaders": ["x-correlation-id"] }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+When both a generic and an event-specific config exist for the same successor type, the event-specific config takes
+precedence. If neither is set, the successor inherits the configuration of its parent action.

src/config.js

@@ -30,6 +30,7 @@ const UTC_DEFAULT = false;
 const USE_CRON_TZ_DEFAULT = true;
 const SAGA_SUCCESS = "#succeeded";
 const SAGA_FAILED = "#failed";
+const SAGA_DONE = "#done";
 
 const BASE_TABLES = {
   EVENT: "sap.eventqueue.Event",
@@ -387,19 +388,20 @@ class Config {
               result.adHoc
             );
             result.adHoc[key] = specificEventConfig;
-            const sagaSuccessKey = [fnName, SAGA_SUCCESS].join("/");
-            if (config.events[sagaSuccessKey]) {
-              const [sagaKey, sagaSpecificEventConfig] = this.addCAPOutboxEventSpecificAction(
-                srvConfig,
-                name,
-                fnName,
-                result.adHoc
-              );
-              result.adHoc[sagaKey] = sagaSpecificEventConfig;
-            } else {
-              const sagaConfig = { ...specificEventConfig };
-              sagaConfig.subType = [sagaConfig.subType, SAGA_SUCCESS].join("/");
-              result.adHoc[[key, SAGA_SUCCESS].join("/")] = sagaConfig;
+            for (const sagaSuffix of [SAGA_SUCCESS, SAGA_DONE, SAGA_FAILED]) {
+              if (config.events[sagaSuffix]) {
+                const [adHocKey, sagaSpecificEventConfig] = this.addCAPOutboxEventSpecificAction(
+                  srvConfig,
+                  name,
+                  fnName,
+                  result.adHoc
+                );
+                result.adHoc[adHocKey] = sagaSpecificEventConfig;
+              } else {
+                const sagaConfig = { ...specificEventConfig };
+                sagaConfig.subType = [sagaConfig.subType, sagaSuffix].join("/");
+                result.adHoc[[key, sagaSuffix].join("/")] = sagaConfig;
+              }
             }
           }
         }
@@ -434,7 +436,7 @@ class Config {
     }
 
     const [withoutSaga, sagaSuffix] = action.split("/");
-    if ([SAGA_FAILED, SAGA_SUCCESS].includes(sagaSuffix)) {
+    if ([SAGA_FAILED, SAGA_SUCCESS, SAGA_DONE].includes(sagaSuffix)) {
       if (config?.events?.[withoutSaga]) {
         return this.#mixCAPPropertyNamesWithEventQueueNames(config.events[withoutSaga]);
       }