Registration

Registration connects a message ID to its transport — a Subject for events and callback messages, a handler function for executors. Nothing can be fired or executed before it is registered: fire throws for unregistered IDs, exec throws for unregistered executors.

Since v3.5 the message-driven flow is the only way to register; the older service methods (record, recordWithPipe, recordExecutor, recordHandler) are deprecated and will be removed.

The Connect messages

import { ConnectMessage, ConnectExecutor, ConnectHandler } from '@artstesh/postboy';
import { Subject } from 'rxjs';

// an event subject (optionally shape the observable subscribers see)
postboy.exec(
  new ConnectMessage(OrderPlacedEvent, new Subject<OrderPlacedEvent>()),
);

// with a pipe — e.g. debounce delivery for chatty events
postboy.exec(
  new ConnectMessage(SearchChangedEvent, new Subject<SearchChangedEvent>(),
    (s) => s.pipe(debounceTime(200))),
);

// a synchronous command handler
postboy.exec(new ConnectExecutor(GetUserNameExecutor, (e) => users[e.userId].name));

// a handler object (testable class-based alternative)
postboy.exec(new ConnectHandler(ParseProductIdExecutor, new ParseProductIdHandler()));

Exact signatures: Infrastructure Messages and the API reference.

Prefer registrators in application code

Bare Connect* calls work but track nothing. A PostboyAbstractRegistrator records every registration and disconnects all of them in one down():

class OrdersRegistrator extends PostboyAbstractRegistrator {
  protected _up(): void {
    this.recordSubject(OrderPlacedEvent);                       // plain Subject
    this.recordReplay(OrdersChangedEvent);                      // latest value on subscribe
    this.recordBehavior(ThemeEvent, new ThemeEvent({ mode: 'dark' })); // state + initial instance
    this.recordExecutor(GetUserNameExecutor, (e) => users[e.userId].name);
  }
}

const orders = new OrdersRegistrator(postboy, 'orders');
orders.up();    // registrations active
orders.down();  // everything disconnected

The registrator's chainable record* methods are not deprecated — they internally use the same Connect* messages. Subject flavors (recordSubject/recordReplay/recordBehavior) are covered in Events.

Rules and semantics

One route per ID. Registering an ID that is already registered overwrites the previous Subject/handler silently (console warning) — the old Subject is dropped without being completed, so its subscribers hang. Avoid double registration; group registrations in registrators.
Register first, subscribe after. Canonical order: define the class with its static ID → register (registrator up() or Connect*) → subscribe → fire/exec.
Unregister deliberately. exec(new DisconnectMessage(SomeMessage.ID)) completes the subject and drops any executor registered under the same ID; further fire/sub of the type throws.

Deprecated service methods

Deprecated on `PostboyService`	Replacement
`record(type, subject)`	`exec(new ConnectMessage(type, subject))`
`recordWithPipe(type, subject, pipe)`	`exec(new ConnectMessage(type, subject, pipe))`
`recordExecutor(type, fn)`	`exec(new ConnectExecutor(type, fn))`
`recordHandler(ctor, handler)`	`exec(new ConnectHandler(ctor, handler))`

Next steps

Lifecycle Management — registrators and teardown.
How It Works — what the store does with a registration.
Caveats — the failure modes of ID reuse.

07 September 2026