Concepts

The model in one paragraph

Every unit of communication is a message — a small typed class carrying a payload and its own unique static readonly ID. The bus routes strictly by that ID string. Participants register what they provide (subjects for events, handlers for commands), then fire, exec, or fireCallback messages. Cross-cutting behavior lives in middleware; grouped registration lifecycle lives in registrators and namespaces.

The three message roles

The comparison, naming conventions, and the message lifecycle are covered in Message Roles; each role has its own chapter: Events, Callbacks, Executors.

Registration and lifecycle

• Registration connects a message ID to a Subject (events/queries) or a handler function (commands). Since v3.5 the bus is mutated only through infrastructure messages — exec(new ConnectMessage(...)) and friends.

• Registrators (PostboyAbstractRegistrator subclasses) group a feature's registrations so one down() call tears them all down. See Lifecycle Management.

• Namespaces name and isolate registrator groups; they scope lifecycle, not message identity. See Namespaces.

Middleware

Every fire/fireCallback/exec passes a staged pipeline (Publish → Callback → Execute). Middleware can filter, observe, or cancel operations by returning an interrupt decision. See Middleware and Middleware Cancellation.

Testing

@artstesh/postboy-testing gives you PostboyWorld: a recording mock of the bus, BDD-style given stubbing, fluent then assertions, and async waiters. See Testing.

Where to go next

• How it works — what happens on the inside of a fire.

• Quick Start — if you skipped straight to theory.

• Best Practices and Caveats — rules that save debugging time.