Messages and Executors Reference

Reference page for the data carriers of @artstesh/postboy (applies to v3.5.x). For the conceptual model see Message roles.

Every message and executor class must declare its own static readonly ID — a class without one throws <ClassName> should have a static ID field on first use, and a subclass that merely inherits its parent's ID silently shares its route.

PostboyMessage

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

abstract class PostboyMessage {
  metadata: PostboyMessageMetadata;                 // {}
  get id(): string;                                 // = constructor.ID
  setMetadata(metadata: Partial<PostboyMessageMetadata>): this;
}

The base of everything that travels through the bus.

Member	Description
`metadata`	Free-form envelope: `correlationId?`, `causationId?`, `tags?: Set<string>`, plus any `[key: string]: any` extras
`id`	The static `ID` of the concrete class — the routing key
`setMetadata(partial)`	Merges into `metadata`, returns the message for chaining

PostboyGenericMessage

abstract class PostboyGenericMessage extends PostboyMessage {}

Base for pub/sub events, dispatched with fire and consumed via sub/once. Payload lives in the concrete class's own constructor fields. See Events.

PostboyCallbackMessage<T>

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

abstract class PostboyCallbackMessage<T> extends PostboyGenericMessage {
  readonly result: Observable<T>;   // view of the internal result subject
  next(value: T): void;             // emit a partial result
  finish(value: T): void;           // emit the final value and complete
  complete(): void;                 // complete without a value
}

Async request/response carrier for fireCallback. The responder subscribes to the message type and calls next/finish on the received instance; the requester consumes the observable. Calling finish completes the result stream — one message instance answers once. See Callbacks.

PostboyExecutor<T>

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

abstract class PostboyExecutor<T> extends PostboyMessage {}

Base for synchronous commands invoked via exec. T is the handler's return type (a phantom parameter — it exists for the type system only). See Executors.

PostboyExecutionHandler<R, E>

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

abstract class PostboyExecutionHandler<R, E extends PostboyExecutor<R>> {
  abstract handle(executor: E): R;
}

The class-based counterpart of an executor lambda. Register with ConnectHandler or a registrator's recordHandler — both are documented in the Infrastructure Messages Reference and the Registrators and Namespaces Reference.

MessageType<T>

type MessageType<T extends PostboyGenericMessage> = new (...args: any[]) => T;

The constructor type accepted by sub, once, registrations, and the testing toolkit — always pass the class itself (PingMessage, not new PingMessage()).

PostboyMessageMetadata / PostboyMessageContext

interface PostboyMessageMetadata {
  correlationId?: string;
  causationId?: string;
  tags?: Set<string>;
  [key: string]: any;
}

interface PostboyMessageContext {
  correlationId: string;
  currentMessageId: string;
  parentMessageId?: string;
  depth: number;
  startedAt: Date;
  tags?: Set<string>;
}

PostboyMessageMetadata is the writable envelope on every message. PostboyMessageContext is the reserved correlation-tracking shape (kept for future/tooling use — the bus itself does not populate it).

PostboySubscription

PostboySubscription — the registration record the store keeps for each message ID — is exported from the package root and documented on the PostboyService Reference.

Not exported from the package root

checkId (the internal static-ID guard), PostboyContextService, PostboyDependencyResolver, IdGenerator — internal machinery; do not import or emulate it.

07 September 2026