@bimetal/alert-data

Der Alert-Zustellungs-Lebenszyklus als EIN Event-Sourcing-Aggregat, multi-entity. Built on @bimetal/event-sourcing. Vorbild: @bimetal/kanban-data, @bimetal/calendar-data.

Jeder Alert ist über einen deterministischen triggerKey keyed (entityId = triggerKey). Das ist die Idempotenz, die Replay/Rehydrate/Sync NIE erneut zustellen lässt — ein Re-ScheduleAlert auf einen existierenden Key und ein Re-RequestAlert eines bereits zugestellten Alerts sind No-ops.

Installation

npm install @bimetal/alert-data @bimetal/event-sourcing

What's Inside

Domain

• Alert — { triggerKey, ruleId, subjectId, channel, recipient, payload, fireAt, status, attempts, lastError? }. triggerKey ist die Entity-ID; channel/recipient sind Strings → keine Abhängigkeit auf @bimetal/channel, der Host mappt den Channel-Namen auf einen echten Channel.
• AlertStatus — scheduled | requested | dispatched | failed | cancelled.
• AlertSpec — was ScheduleAlert trägt.

Lebenszyklus (Commands → Events)

| Command | Event | Idempotenz | |---|---|---| | ScheduleAlert(spec) | AlertScheduled | existiert triggerKey schon → No-op | | RequestAlert(key) | AlertRequested | auf requested/dispatched/cancelled → No-op (das Exactly-once-Gate) | | MarkDispatched(key) | AlertDispatched | nur auf requested; doppelt → No-op | | MarkFailed(key, error) | AlertFailed | nur auf requested; attempts++, errors-as-state | | CancelAlert(key) | AlertCancelled | auf dispatched/cancelled → No-op |

failed → RequestAlert ist erlaubt (Retry). Command-Creators: scheduleAlert, requestAlert, markDispatched, markFailed, cancelAlert.

Store

• createAlertStore(config?) — verdrahtet das Aggregat über createDomainStore. Facade AlertStore mit getAlerts(), getAlert(triggerKey), getByStatus(status) plus dem generischen dispatch/rebuild.
• AlertReadModel — { alerts: Record<triggerKey, Alert>, version } (prototype-sicher).

Designprinzipien

• Idempotenz strukturell, nicht nur über das Command-ID-Fenster. Schicht 1 = processedCommandIds (50 tief, Optimierung); Schicht 2 = state.events.has(triggerKey) — unbegrenzt, trägt jeden sendrelevanten Übergang.
• Opake Payload. Das Aggregat speichert die pre-renderte Nachricht als unknown + Channel-Name als String. Der Store-eigene structuredClone am dispatch-Eingang validiert (verwirft non-cloneable Payload) und detacht von der Caller-Referenz — das Aggregat braucht keinen eigenen Payload-Guard.
• Keine externen Side-Effects. Senden gehört in @bimetal/alerting; dieses Paket ist reines, replaybares Zustands­management.

License

Apache License 2.0