Typed Event‑Driven Architecture for TypeScript Applications

Postboy is a lightweight, framework‑agnostic Pub/Sub library that brings structured event‑driven communication to your frontend or Node.js projects.
It replaces scattered service calls and deep component chains with a single typed message bus — making your code predictable, decoupled, and easy to change.

1. The problem Postboy solves

In traditional applications, a user action often travels through multiple layers:

Component → Service A → Component B → Service C → UI update

This leads to:

Prop drilling & long @Input/@Output chains in component frameworks.
Tight coupling between unrelated parts of the system.
High maintenance cost — adding a new side effect requires changes in several files.

As a codebase grows, understanding the flow of data and control becomes harder.

2. How Postboy changes the picture

Postboy introduces a central message bus that components and services talk to directly.
Instead of calling each other, they exchange typed messages — commands, queries, events, and executors.

Component A → bus.exec(DoSomethingCommand) → bus → handler 
   → bus.pub(SomethingHappenedEvent) → Component B

Every participant depends only on the bus and the message contracts.
The result is a clean, event‑driven architecture with minimal coupling.

3. Core concepts

Concept	Description	Link to section
Generic Messages	Fire‑and‑forget events; perfect for domain events and UI notifications.	Generic Messages
Callback Messages	Request‑response style communication; typed results returned to the sender.	Callback Messages
Executors	Synchronous operations executed directly through the bus.	Executors
CQRS‑style Message Roles	Organise messages as Queries, Commands, Events, and Executors for maximum readability.	Message Roles
Lifecycle Management & Scoping	Registrators, namespaces, and depending services that automate subscription cleanup.	Lifecycle Management
Middleware	Intercept messages before/after processing for logging, validation, or custom policies.	Middleware

4. Quick example

Below is a minimal taste of how Postboy looks in code.

Firing an event

import {PostboyGenericMessage} from '@artstesh/postboy';

class OrderPlacedEvent extends PostboyGenericMessage {
  static readonly ID = 'order.placed';

  constructor(public readonly orderId: string) {
    super();
  }
}

// Publish
postboy.fire(new OrderPlacedEvent('ORD‑42'));

Listening to an event

postboy.sub(OrderPlacedEvent).subscribe((msg) => {
  console.log('Order placed:', msg.orderId);
});

Requesting data with a callback message

class GetUserQuery extends PostboyCallbackMessage<User | null> {
  static readonly ID = 'user.get';

  constructor(public readonly userId: string) {
    super();
  }
}

// Fire and receive a typed response
postboy.fireCallback(new GetUserQuery('42')).subscribe((user) => {
  if (user) {
    console.log(user.name);
  }
});

Everything is type‑safe, framework‑agnostic, and uses RxJS under the hood.

5. Why choose Postboy?

Framework‑agnostic — works with Angular, React, Vue, Node.js, or plain TypeScript.
Typed from end to end — message contracts are TypeScript classes with explicit payloads and (where applicable) return types.
No manual subscription management — registrators, namespaces, and depending services clean up automatically.
CQRS‑ready — recommended naming and folder conventions keep large codebases navigable.
Middleware support — hook into message flows without touching business logic.
Tiny footprint — focused library, no hidden dependencies beyond RxJS.

6. Next steps

Start with the Quick Start Guide to set up your first message.
Explore Generic Messages for fire‑and‑forget events.
Learn about Callback Messages for request‑response patterns.
See how to Organise Messages by Role for a CQRS‑style architecture.
Master Lifecycle Management to never worry about memory leaks again.

Postboy is the backbone that lets your application grow without turning into a tangled web of dependencies. Give it a try — your future self will thank you.

23 апреля 2026