@bimetal/broker

@bimetal/broker

Generic pluggable message broker abstraction. Domain-agnostic pub/sub mit Capability-Modell. In-Process-Default; externe Adapter (Kafka, RabbitMQ, NATS, …) implementieren das gleiche Interface.

Zero external dependencies. Zero @bimetal/* dependencies. Standort im Stack neben @bimetal/event-sourcing: beide sind Architektur-Primitive, keine domain-spezifischen Packages.

Installation

npm install @bimetal/broker

What's Inside

Types

• Broker<TMessage = unknown> — generic pub/sub-Interface (publish, subscribe, optional subscribePattern, optional close)
• BrokerCapabilities — { patterns, replay, ordering }. Einzige Quelle der Wahrheit für Adapter-Fähigkeiten.
• BrokerErrorHandler, BrokerErrorContext — Fehler-Isolation: ein werfender Handler darf andere nicht blockieren.
• MessageHandler<TMessage>, Topic, TopicPattern, Unsubscribe

In-Process-Default

• createInProcessBroker(options?) — Default-Adapter, RabbitMQ-Style Wildcards, async via queueMicrotask, flush() als Test-Helfer.
• InProcessBroker<TMessage> — Broker<TMessage> & { flush(): Promise<void> }. flush() ist bewusst nicht im Hauptinterface.

Topic-/Pattern-Utilities

• assertValidTopic(topic), assertValidPattern(pattern) — werfen bei syntaktischen Fehlern.
• topicMatchesPattern(topic, pattern) — RabbitMQ-Topic-Match (* = ein Segment, # = mehrere).

Designprinzipien

• Generic over TMessage: kein DomainEvent-Lock-in. Konsumenten typisieren z. B. Broker<DomainEvent> und liefern Helper wie eventToTopic separat.
• Async-Vertrag: publish() resolved, sobald Zustellung geplant ist — nicht „handled". In-Process via queueMicrotask; externe Adapter heißt „ack vom Broker erhalten".
• Capabilities zuerst: Adapter-Unterschiede werden explizit über capabilities kommuniziert, nicht durch Anwesenheit/Abwesenheit von Methoden.
• Wildcards getrennt: subscribe (exakt) und subscribePattern (mit */#) sind getrennt. Adapter, die keine Wildcards können (Kafka), setzen capabilities.patterns = false und werfen oder weglassen.
• Fehler-Isolation: Subscriber-Exceptions stoppen die Zustellung an Geschwister nicht. onError macht Fehler sichtbar — nicht schluckend, nicht blockierend.
• Keine EventStore-Kopplung: Bridge EventStore → Broker ist bewusst außerhalb dieses Packages, immer opt-in, immer post-append.

Status

Teil der Broker-Abstraktion. Adapter für Kafka (@bimetal/broker-kafka), RabbitMQ (@bimetal/broker-rabbitmq), Web Worker (@bimetal/broker-worker) und BroadcastChannel (@bimetal/broker-broadcast) sind ausgeliefert.