Postboy Help

API Reference

Reference for the public API of the two published packages: @artstesh/postboy (the message bus, applies to v3.5.x) and @artstesh/postboy-testing (the BDD testing toolkit, applies to v3.4.x, peers @artstesh/postboy ^3.4.1). For the conceptual model behind these APIs, see Concepts and How it works.

What the public API covers

The public API is the user-facing layer of Postboy: a typed, structured way to work with event-driven communication without depending on internal mechanics. It includes:

  • The bus — PostboyService with the verbs fire, fireCallback, sub, once, exec, and dispose.

  • Messages — PostboyMessage, PostboyGenericMessage (events), PostboyCallbackMessage<T> (request/response), and PostboyExecutor<T> (synchronous commands), plus their metadata types.

  • Registration and lifecycle — PostboyAbstractRegistrator, IPostboyDependingService, and the namespace machinery.

  • Infrastructure messages — Connect*, DisconnectMessage, lock/unlock, middleware, and namespace messages; the only way to mutate the bus since v3.5.

  • Middleware — the staged pipeline: PostboyMiddleware, stages, decisions, pipeline contexts, and cancellation types.

  • The testing toolkit — PostboyWorld, the recording PostboyServiceMock, given/then/waiter services, message history, and the boolean verifier.

Design principles: typed first, framework-agnostic, message-driven (bus operations are messages too), extensible, and consistent across similar operations.

Reference map

Every part of the public API has a dedicated reference page:

Area

Page

The bus — fire, fireCallback, sub, once, exec, dispose, PostboySubscription

PostboyService Reference

Data carriers — PostboyMessage, PostboyGenericMessage, PostboyCallbackMessage, PostboyExecutor, handlers, metadata

Messages and Executors Reference

Lifecycle owners — PostboyAbstractRegistrator, IPostboyDependingService, namespace and message stores

Registrators and Namespaces Reference

The pipeline contract — PostboyMiddleware, stages, decisions, CancelError

Middleware Reference

Bus mutations — Connect*, DisconnectMessage, lock and namespace messages

Infrastructure Messages Reference

The testing toolkit — PostboyWorld, mock, given/then/waiter

Postboy-Testing Reference

Reading conventions

  • Named exports only. Neither package has a default export. Always import symbols by name from the package root; sub-paths are not part of the public surface.

  • Dual ESM/CJS build. Since v3.4 both packages ship a dual-format build: lib/index.mjs for ESM/TypeScript consumers and lib/index.cjs for CommonJS, selected automatically by the package exports map.

// ESM / TypeScript import { PostboyService, PostboyGenericMessage } from '@artstesh/postboy'; // CommonJS const { PostboyService } = require('@artstesh/postboy');

  • Routing is keyed by static ID. Every message and executor class declares its own unique static readonly ID; all bus lookups use that string, not class identity.

  • Truth source. These pages are written against the installed versions. When in doubt, verify signatures in node_modules/@artstesh/postboy/lib/index.d.ts (or the equivalent in @artstesh/postboy-testing).

  • Deprecation policy. Methods marked deprecated still work in the 3.x line and are scheduled for removal in the next major line; each one lists its replacement. See Versions for the version lines and release notes.

07 September 2026
VuePostboyService Reference