first commit

2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
--- a/docs/api-stack/api/api-plugin-event-bus/src/error-codes/error-codes.md
+++ b/docs/api-stack/api/api-plugin-event-bus/src/error-codes/error-codes.md
@@ -0,0 +1,104 @@
+# `error-codes.ts` — `EventBusError` and the 8-code registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Declares the stable error-code registry consumed by every failure path
+in `@suaveplan/api-plugin-event-bus`. The registry is built via
+`defineCodes("EVENT_BUS", [...])` from `@suaveplan/error` so the
+exported `EVENT_BUS_CODES` object is a frozen record whose values are
+`` `EVENT_BUS.${string}` `` literal types — consumers branch on the
+string value (e.g. `error.code === EVENT_BUS_CODES.INVALID_TOPIC`)
+with full TypeScript narrowing.
+
+The matching `EventBusError` class extends `SuaveplanError` and tags
+the supplied code on `this.eventBusCode` for symmetric narrowing in
+`instanceof` checks.
+
+## Features
+
+- 8 stable codes (`INVALID_INPUT`, `INVALID_TOPIC`, `SERVICE_NOT_AVAILABLE`,
+  `ROUTE_PREFIX_COLLISION`, `SUBSCRIPTION_NOT_FOUND`,
+  `BACKPRESSURE_DROPPED`, `TENANT_MISMATCH`, `PUBLISH_FAILED`).
+- Strongly-typed registry via `defineCodes`.
+- `EventBusError` extends `SuaveplanError<EventBusErrorCode>` so the
+  `code` discriminator narrows to the registry literal.
+- Compatible with the shared error-handler middleware in
+  `@suaveplan/api` (the HTTP status code is carried on `context.statusCode`).
+
+## Usage: Basic
+
+```ts
+import {
+    EVENT_BUS_CODES,
+    EventBusError,
+} from "@suaveplan/api-plugin-event-bus/error-codes/error-codes";
+
+throw new EventBusError(EVENT_BUS_CODES.INVALID_TOPIC, "topic invalid", {
+    context: { topic: "Order Created", statusCode: 400 },
+});
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    EVENT_BUS_CODES,
+    EventBusError,
+} from "@suaveplan/api-plugin-event-bus/error-codes/error-codes";
+
+function handle(err: unknown): number {
+    if (!(err instanceof EventBusError)) return 500;
+    switch (err.eventBusCode) {
+        case EVENT_BUS_CODES.INVALID_TOPIC:
+        case EVENT_BUS_CODES.INVALID_INPUT:
+            return 400;
+        case EVENT_BUS_CODES.SUBSCRIPTION_NOT_FOUND:
+        case EVENT_BUS_CODES.TENANT_MISMATCH:
+            return 404;
+        case EVENT_BUS_CODES.BACKPRESSURE_DROPPED:
+            return 503;
+        case EVENT_BUS_CODES.ROUTE_PREFIX_COLLISION:
+        case EVENT_BUS_CODES.SERVICE_NOT_AVAILABLE:
+        case EVENT_BUS_CODES.PUBLISH_FAILED:
+            return 500;
+        default:
+            return 500;
+    }
+}
+```
+
+## API Reference
+
+### `EVENT_BUS_CODES`
+
+`Readonly<Record<EventBusErrorCode, ``EVENT_BUS.${EventBusErrorCode}``>>`
+— frozen registry, keys listed above.
+
+### `type EventBusErrorCode`
+
+Union of every value in `EVENT_BUS_CODES`. Used as the discriminator
+type parameter on `EventBusError`.
+
+### `class EventBusError extends SuaveplanError<EventBusErrorCode>`
+
+- `constructor(code: EventBusErrorCode, message: string, options?: SuaveplanErrorOptions)`.
+- `eventBusCode: EventBusErrorCode` — duplicate of `this.code` retained
+  for symmetric narrowing in `instanceof` checks (`SuaveplanError`'s
+  `code` is typed as the generic parameter).
+
+## Implementation Notes
+
+- Codes are deliberately additive — removing one is a breaking change
+  for consumers asserting on `error.code === "EVENT_BUS.<X>"`. New codes
+  may be added at the end of the `defineCodes` array.
+- The package-level `EventBusError` constructor is `public` so callers
+  may construct errors directly (`SuaveplanError`'s base constructor is
+  `protected`). This matches the pattern used by
+  `@suaveplan/api-plugin-auth`'s `AuthError`.
+- `context.statusCode` is the canonical carrier for the HTTP status the
+  error-handler should emit; the table in the Advanced example mirrors
+  the mapping used by `@suaveplan/api`'s default error handler.