Overview
The model in nine pieces — what a notifiable and a notification are, the channel/dispatcher split, and the behaviours layered on top — async delivery, tenancy, attribution, guards, fallbacks and locales.
Two nouns and one split carry the whole library. Read the first three pages in order; the rest are behaviours you opt into when you need them.
The model
- Notifiables — anything that can receive a notification. Per-channel
addresses come from
@RouteFordecorators, and@NotifiableIdmarks the id. - Notifications — a plain class. Annotate each payload method with
its channel handle (
@Mail(),@Database()) andvia()is inferred for you. - Channels & dispatchers — the split everything else hangs off: a channel decides how a notification leaves, a dispatcher decides where and when it runs.
Delivery
- Async dispatch — what survives the trip to a worker: a
notification serializes to
{ name, data }, a notifiable to a reference. - Fallback chains — an ordered chain of channels, stopping at the first that reaches the recipient.
- Dispatch guards — dedup and throttle before any channel runs.
Per-recipient concerns
- Multi-tenancy — the same user in many workspaces, each with its
own feed; scope one send or fan out with
forTenant. - Localization — resolve a locale off the notifiable and translate per recipient.
- Context capture — who triggered this, in which tenant, under which trace, threaded through the lifecycle events.
Getting Started
Send your first notification in an existing NestJS app — install the core and a channel, write a notification class, and call send(). Synchronous by default; add a queue when you're ready.
Notifiables
A notifiable is anything that can receive a notification. Declare per-channel addresses with @RouteFor decorators and mark the id with @NotifiableId — no routeNotificationFor switch, no manual toNotifiableRef.