Registrators and Namespaces Reference

Reference page for the lifecycle machinery of @artstesh/postboy (applies to v3.5.x). For the conceptual model see Lifecycle management and Namespaces.

PostboyAbstractRegistrator

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

abstract class PostboyAbstractRegistrator {
  constructor(postboy: PostboyService, namespace: string | null = null);
  get namespace(): string;

  registerServices(services: IPostboyDependingService[]): void;
  up(): void;                    // _up(), then each service's up()
  down(): void;                  // each service's down(), then DisconnectMessage per recorded id
  protected abstract _up(): void;

  // chainable — return this; execute the Connect* messages and track the ids:
  record<T>(type: MessageType<T>, sub: Subject<T>): this;
  recordWithPipe<T>(type: MessageType<T>, sub: Subject<T>, pipe: (s: Subject<T>) => Observable<T>): this;
  recordExecutor<E extends PostboyExecutor<T>, T>(type: new (...args: any[]) => E, exec: (e: E) => T): this;
  recordHandler<E extends PostboyExecutor<R>, R>(executor: new (...args: any[]) => E, handler: PostboyExecutionHandler<R, E>): this;
  recordReplay<T>(type: MessageType<T>, bufferSize = 1): this;
  recordBehavior<T>(type: MessageType<T>, initial: T): this;
  recordSubject<T>(type: MessageType<T>): this;
}

Groups a feature's registrations under one lifecycle. The record* methods are not deprecated — unlike the same-named methods on PostboyService — they execute the infrastructure messages internally and remember the IDs so down() disconnects them all.

Member	Description
`constructor(postboy, namespace?)`	Takes the bus and an optional namespace name; `null` (or omitted) generates a random name
`namespace`	The registrator's namespace name — pass it to `EliminateNamespace` for external teardown
`registerServices(services)`	Links lifecycle-aware services; their `up()` runs after `_up()`'s registrations, `down()` before the disconnections
`up()`	Calls `_up()`, then each registered service's `up()` — activate as early as the feature needs
`down()`	Calls each service's `down()`, executes a `DisconnectMessage` for every recorded ID, and clears the service list
`_up()`	The abstract hook where a subclass records its messages and handlers

Subject types by method:

Method	Subject created	Notes
`recordSubject(type)`	`Subject`	plain pub/sub
`recordReplay(type, bufferSize = 1)`	`ReplaySubject(bufferSize)`	late subscribers get the last N messages
`recordBehavior(type, initial)`	`BehaviorSubject`	the initial value is a message instance, not a plain value
`record(type, sub)`/`recordWithPipe(type, sub, pipe)`	yours	you construct the `Subject`; the optional pipe shapes the observable `sub` hands out

For the conceptual walkthrough see Registration.

IPostboyDependingService

interface IPostboyDependingService {
  up(): void;      // subscribe/start — runs after the registrator's registrations
  down?(): void;   // optional teardown — runs before the disconnections
}

A service that participates in a registrator's lifecycle. Register it with registerServices([...]); the execution order of up()/down() relative to the message registrations is documented in Lifecycle management.

Namespaces

Registrators created through exec(new AddNamespace(space)) are eliminated with exec(new EliminateNamespace(space)) — the returned registrator's down() runs, disconnecting everything it recorded. Both messages, their exact signatures, and their repeat-call semantics are documented in the Infrastructure Messages Reference.

Registrations live in one shared store keyed by message ID, regardless of namespaces — recording the same type in a second namespace overwrites the first registration. See Namespaces.

PostboyNamespaceStore

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

class PostboyNamespaceStore {
  addSpace(space: string, postboy: PostboyService): PostboyAbstractRegistrator;
  eliminateSpace(space: string): void;
  dispose(): void;
}

The registry behind AddNamespace/EliminateNamespace.

Method	Description
`addSpace(space, postboy)`	Returns the registrator of the name, creating it on first use; a repeated call returns the same instance
`eliminateSpace(space)`	Calls `down()` on the namespace's registrator — disconnecting everything it recorded — and removes it; unknown names are ignored
`dispose()`	Tears down every namespace; called by `PostboyService.dispose()`

PostboyMessageStore

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

class PostboyMessageStore {
  registerMessage(id: string, sub: PostboySubscription<any>): void;
  registerExecutor(id: string, executor: (e: PostboyExecutor<any>) => any): void;
  getMessage(id: string, name: string): PostboySubscription<any>;
  getExecutor<T>(id: string): (e: PostboyExecutor<T>) => T;
  unregister(id: string): void;
  dispose(): void;
}

The registry of message subjects and executor handlers.

Method	Description
`registerMessage`/`registerExecutor`	Puts a registration; re-registering an existing ID logs `Message with id <id> already registered. Overriding...` and replaces it
`getMessage(id, name)`	Returns the subscription; throws `There is no registered event <name>` when absent
`getExecutor(id)`	Returns the handler; throws `There is no registered executor with id <id>` when absent
`unregister(id)`	Completes the subject, runs the registered completion callbacks, and drops the message, callback, and executor entries for that ID
`dispose()`	Unregisters everything; called by `PostboyService.dispose()`

Exported for typing and test doubles — the testing toolkit mocks it. Applications manage registrations through registrators or the infrastructure messages, never through the store directly.

Not exported from the package root

PostboyDependencyResolver (assembles the internal collaborators) and PostboyContextService (orphaned correlation tracking based on node:async_hooks, server-only) — internal machinery; do not import or emulate it.

07 September 2026