@artstesh/postboy 3.5.0 → 3.5.2

package/lib/index.d.mts

@@ -1,689 +1,1010 @@
 import { Subject, Observable } from 'rxjs';
 
 /**
- * Represents metadata associated with a Postboy message.
- *
- * This interface can be used to store optional metadata that provides
- * additional context or tracking information for a message. It supports
- * flexible extension by allowing additional properties through an index signature.
- *
- * Properties:
- * - `correlationId` (optional): A unique identifier used to correlate
- *   related messages or operations across systems.
- * - `causationId` (optional): The identifier of the preceding message
- *   or event that caused the current message to be produced.
- * - `source` (optional): The origin or source of the message, such as
- *   a particular service or system.
- * - `tags` (optional): An array of tags or labels that can be attached
- *   to the message for categorization, filtering, or logging purposes.
- * - `[key: string]` (optional): Additional custom properties can be
- *   added to capture specific metadata not covered by the predefined fields.
+ * Free-form metadata attached to a message via `PostboyMessage.setMetadata`.
+ *
+ * The predefined fields describe message correlation and causality; the index signature
+ * accepts any custom key.
  */
 interface PostboyMessageMetadata {
+    /** Ties together all messages belonging to one logical operation or request. */
     correlationId?: string;
+    /** The `id` of the message that directly caused this one, when causality is tracked. */
     causationId?: string;
+    /** Free-form labels used for categorization, filtering, or logging. */
     tags?: Set<string>;
+    /** Any custom key-value data. */
     [key: string]: any;
 }
 
+/**
+ * Root of the message hierarchy — anything that travels through the bus.
+ *
+ * A message is a plain data carrier: dispatch behavior comes from the subclasses.
+ * {@link PostboyGenericMessage} is the base for pub/sub messages, and
+ * {@link PostboyExecutor} carries a synchronous command. The bus routes every one of
+ * them by the static `ID` of the concrete class, exposed per instance by {@link id}.
+ */
 declare abstract class PostboyMessage {
+    /** Free-form data attached to the message; populate it via {@link setMetadata}. */
     metadata: PostboyMessageMetadata;
+    /** The static `ID` of the concrete message class — the key the bus routes by. */
     get id(): string;
+    /**
+     * Shallow-merges the given fields into {@link metadata}.
+     *
+     * @param metadata - Fields to add or override.
+     * @return This message, for chaining.
+     */
     setMetadata(metadata: Partial<PostboyMessageMetadata>): this;
 }
 
 /**
- * An inheritor should have a static ID field
+ * Base class for pub/sub messages — the "letters" carried by the bus.
+ *
+ * A subclass must declare its own `static readonly ID` (a unique string): registration,
+ * subscription, locking, and dispatch are all keyed by that `ID`, not by class identity.
+ * Inheriting a parent's `ID` makes two message types silently collide on one registration.
+ *
+ * @example
+ * ```ts
+ * class PingMessage extends PostboyGenericMessage {
+ *   static readonly ID = 'app.ping';
+ *   constructor(public text: string) {
+ *     super();
+ *   }
+ * }
+ * ```
  */
 declare abstract class PostboyGenericMessage extends PostboyMessage {
 }
 
+/**
+ * Base class for synchronous commands executed via `PostboyService.exec`.
+ *
+ * An executor is a short-lived value object: construct it with the command arguments and
+ * pass it to `exec`, which invokes the handler registered for the class's static `ID`
+ * and returns its result synchronously. For asynchronous results use a
+ * {@link PostboyCallbackMessage} instead.
+ *
+ * @example
+ * ```ts
+ * class GetDataExecutor extends PostboyExecutor<string> {
+ *   static readonly ID = 'app.get-data';
+ *   constructor(public key: string) {
+ *     super();
+ *   }
+ * }
+ *
+ * postboy.exec(new ConnectExecutor(GetDataExecutor, (e) => store.get(e.key)));
+ * const value: string = postboy.exec(new GetDataExecutor('foo'));
+ * ```
+ */
 declare abstract class PostboyExecutor<T> extends PostboyMessage {
+    /**
+     * Phantom marker existing only at the type level: it ties the class to its result type
+     * `T` so `exec` can infer it. Erased at runtime — never assign to it.
+     */
     protected readonly _postboyResultType?: T;
 }
 
 /**
- * An abstract class extending PostboyGenericMessage that provides mechanisms for managing
- * asynchronous data communication using RxJS observables. It is designed to work with
- * callback-based operations that emit a result of type T.
- *
- * @template T - The type of the data emitted by the observables in this class.
+ * Base class for async request/response messages: the requester fires it via
+ * `PostboyService.fireCallback`, a responder — subscribed to the message type — produces
+ * the result through {@link next} or {@link finish}, and the requester observes the
+ * values on {@link result}.
  *
- * @extends PostboyGenericMessage
+ * Use a callback message when the result arrives asynchronously; for synchronous
+ * results use a {@link PostboyExecutor} instead.
  *
- * @property {Observable<T>} result - An observable that emits the result of the operation
- * and completes once the operation is finished.
+ * @example
+ * ```ts
+ * class FetchDataMessage extends PostboyCallbackMessage<string> {
+ *   static readonly ID = 'app.fetch-data';
+ * }
  *
- * @method next - Emits the next value for the result observable.
- * @param {T} value - The value to be emitted by the result observable.
- *
- * @method finish - Emits the final value for the result observable and completes it.
- * @param {T} value - The final value for the observable emission.
+ * // responder: produces the result
+ * postboy.sub(FetchDataMessage).subscribe((m) => m.finish('payload'));
+ * // requester: consumes it
+ * postboy.fireCallback(new FetchDataMessage()).subscribe((payload) => console.log(payload));
+ * ```
  */
 declare abstract class PostboyCallbackMessage<T> extends PostboyGenericMessage {
+    /** The subject backing {@link result}; protected so only subclass/responder code can emit. */
     protected result$: Subject<T>;
+    /** The observable of result values; completed by {@link finish}, {@link complete}, or a `DisconnectMessage`. */
     result: Observable<T>;
     /**
-     * Emits the provided value.
+     * Emits an intermediate result value to every {@link result} subscriber without
+     * completing the stream — for operations that produce several values.
      *
-     * @template T - The type of the value to emit.
-     * @param {T} value - The value to emit through the `result$` observable.
-     * @returns {void}
+     * @param value - The value to emit.
      */
     next: (value: T) => void;
     /**
-     * Marks the operation as complete by emitting the provided value and then completing the result stream.
+     * Emits the final result value and completes {@link result}.
      *
-     * @param {T} value - The value to emit prior to completing the result stream.
-     * @return {void} This method does not return a value.
+     * @param value - The last value to emit.
      */
     finish(value: T): void;
-    /**
-     * Completes the current observable result stream.
-     * This method marks the result observable as complete, ensuring no further values
-     * or events will be emitted from it.
-     *
-     * @return {void} No value is returned from this method.
-     */
+    /** Completes {@link result} without emitting another value. */
     complete(): void;
 }
 
+/**
+ * A service sharing the lifecycle of the {@link PostboyAbstractRegistrator} it is
+ * attached to via `registerServices`.
+ */
 interface IPostboyDependingService {
+    /**
+     * Called by `PostboyAbstractRegistrator.up()` after the registrator's own
+     * registrations are done. Start or initialize the service here.
+     */
     up(): void;
-    down?: () => void;
+    /**
+     * Optional teardown: called by `PostboyAbstractRegistrator.down()` before the
+     * registrator disconnects its recorded messages. Release resources here.
+     */
+    down?(): void;
 }
 
 /**
- * Abstract class representing a handler for executing a Postboy task.
+ * Base class for class-based executor handlers — the object-oriented alternative to the
+ * `(e) => result` function accepted by `ConnectExecutor`.
  *
- * This class is intended to manage the execution flow of a PostboyExecutor instance.
- * Subclasses must implement the `handle` method, which executes a given PostboyExecutor
- * and returns a result of type R.
+ * Register an instance with `ConnectHandler` (or `PostboyAbstractRegistrator.recordHandler`);
+ * {@link handle} is then invoked on every `PostboyService.exec` of the executor type.
  *
- * @template R The type of the result returned by the `handle` method.
- * @template E The type of the executor extending the PostboyExecutor.
+ * @template R - Result type returned by {@link handle}.
+ * @template E - The executor type this handler serves.
  */
 declare abstract class PostboyExecutionHandler<R, E extends PostboyExecutor<R>> {
     /**
-     * Abstract method to handle the specified executor and return a result.
+     * Processes an executor command and returns its result synchronously.
      *
-     * @param {E} executor - The executor that will be processed by the method.
-     * @return {R} The result obtained after handling the executor.
+     * @param executor - The executor instance passed to `PostboyService.exec`.
+     * @return The result handed back to the caller of `exec`.
      */
     abstract handle(executor: E): R;
 }
 
+/**
+ * Constructor signature of a message class.
+ *
+ * The bus identifies message types by the static `ID` such a constructor carries (see
+ * {@link PostboyGenericMessage}), not by class identity — two different classes sharing
+ * an `ID` collide on the same registration (the later one overrides the earlier one
+ * with a warning).
+ */
 type MessageType<T extends PostboyGenericMessage> = new (...args: any[]) => T;
+/**
+ * Base class for feature registrators: registers messages and executors for one feature
+ * and remembers every recorded `ID`, so that a single {@link down} disconnects them all.
+ *
+ * Subclasses make their `record*` calls inside the abstract {@link _up} hook; services
+ * attached via {@link registerServices} share the same lifecycle. Create one registrator
+ * per feature (or per namespace, via `AddNamespace`) and keep the instance to tear the
+ * feature down later.
+ *
+ * @example
+ * ```ts
+ * class FeatureRegistrator extends PostboyAbstractRegistrator {
+ *   protected _up(): void {
+ *     this.recordSubject(PingMessage).recordExecutor(GetDataExecutor, (e) => e.payload);
+ *   }
+ * }
+ *
+ * const reg = new FeatureRegistrator(postboy, 'feature-a');
+ * reg.up(); // registrations are live
+ * reg.down(); // everything recorded above is disconnected
+ * ```
+ */
 declare abstract class PostboyAbstractRegistrator {
     protected postboy: PostboyService;
+    /**
+     * Identifier of this registrator: the name passed to the constructor, or a generated
+     * unique id when none was given. It identifies the registrator only — message routing
+     * is not affected by it.
+     */
     get namespace(): string;
     private ids;
     private services;
     private readonly _namespace;
+    /**
+     * @param postboy - The bus every `record*` call is executed on.
+     * @param namespace - Optional name exposed by {@link namespace}; a random unique id is generated when omitted.
+     */
     constructor(postboy: PostboyService, namespace?: string | null);
     /**
-     * Registers a list of services to be used by the application.
+     * Sets the services that share this registrator's lifecycle: their `up()` runs on
+     * {@link up} (after the registrations), their `down()` on {@link down} (before the
+     * disconnection). Replaces any previously registered list.
      *
-     * @param {IPostboyDependingService[]} services - An array of services to register.
-     * @return {void} This method does not return a value.
+     * @param services - Services to attach to the lifecycle.
      */
     registerServices(services: IPostboyDependingService[]): void;
     /**
-     * Initiates the 'up' process for the current instance and all associated services.
-     *
-     * @return {void} Does not return a value.
+     * Activates the registrator: runs the {@link _up} registration hook, then calls `up()`
+     * on every attached service.
      */
     up(): void;
+    /**
+     * Registration hook executed by {@link up}. Subclasses make all their `record*` calls
+     * here so that {@link down} can disconnect them.
+     */
     protected abstract _up(): void;
+    /**
+     * Tears the registrator down, in order: calls `down()` on every attached service (then
+     * clears the service list), then executes a `DisconnectMessage` for each recorded `ID`,
+     * completing subscriber streams and removing handlers registered by this registrator.
+     */
     down(): void;
     /**
-     * Records a type and its corresponding Subject<T> into the Postboy system and updates the internal identifiers.
+     * Registers a message type with the given subject and remembers its `ID` for {@link down}.
      *
-     * @param {MessageType<T>} type - A constructor for the generic message type T.
-     * @param {Subject<T>} sub - The subject associated with the generic message type.
-     * @return {this} Returns the current instance for method chaining.
+     * @param type - The constructor of the message type; must declare its own static `ID`.
+     * @param sub - The subject subscribers will observe.
+     * @return This registrator, for chaining.
      */
     record<T extends PostboyGenericMessage>(type: MessageType<T>, sub: Subject<T>): PostboyAbstractRegistrator;
     /**
-     * Records a message type with a specific subject and applies a transformation pipe to the subject.
+     * Registers a message type whose stream is transformed by a pipe before reaching
+     * subscribers, and remembers its `ID` for {@link down}.
      *
-     * @param {MessageType<T>} type - The constructor of the message type to record, which extends PostboyGenericMessage.
-     * @param {Subject<T>} sub - The Subject instance to associate with the message type.
-     * @param {(s: Subject<T>) => Observable<T>} pipe - A function that takes the subject as input and returns an Observable with transformations applied.
-     * @return {this} The current instance of the class for chaining.
+     * @param type - The constructor of the message type; must declare its own static `ID`.
+     * @param sub - The subject subscribers will observe.
+     * @param pipe - Wraps the subject into the observable handed out by `PostboyService.sub`, e.g. to apply operators.
+     * @return This registrator, for chaining.
      */
     recordWithPipe<T extends PostboyGenericMessage>(type: MessageType<T>, sub: Subject<T>, pipe: (s: Subject<T>) => Observable<T>): PostboyAbstractRegistrator;
     /**
-     * Records an executor associated with a specific type and execution logic.
+     * Registers a synchronous handler for an executor type and remembers its `ID` for {@link down}.
      *
-     * @param type The class constructor of the executor type to be recorded, which extends PostboyExecutor.
-     * @param exec A callback function that executes the logic using an instance of the specified executor type.
-     * @return void
+     * @param type - The constructor of the executor class; must declare its own static `ID`.
+     * @param exec - Called with the executor instance on every `PostboyService.exec` of this type.
+     * @return This registrator, for chaining.
      */
     recordExecutor<E extends PostboyExecutor<T>, T>(type: new (...args: any[]) => E, exec: (e: E) => T): PostboyAbstractRegistrator;
     /**
-     * Records a handler for a specific executor type.
+     * Registers a {@link PostboyExecutionHandler} for an executor type and remembers its
+     * `ID` for {@link down}. The handler's `handle` method is invoked on every
+     * `PostboyService.exec` of this type.
      *
-     * @param executor The constructor of the executor type, which extends `PostboyExecutor`.
-     * @param handler The execution handler associated with the given executor type.
-     * @return void
+     * @param executor - The constructor of the executor class; must declare its own static `ID`.
+     * @param handler - The handler instance receiving the executor.
+     * @return This registrator, for chaining.
      */
     recordHandler<E extends PostboyExecutor<R>, R>(executor: new (...args: any[]) => E, handler: PostboyExecutionHandler<R, E>): PostboyAbstractRegistrator;
     /**
-     * A utility function that facilitates the recording and replaying of messages
-     * using a ReplaySubject. This function is designed to handle messages of a
-     * specific type and allows specifying a buffer size to determine how many
-     * of the most recent messages should be replayed.
+     * Registers the type with a `ReplaySubject`: new subscribers first receive up to
+     * `bufferSize` most recently fired messages, then live ones. Suited for
+     * "latest events" streams where late subscribers need recent history.
      *
-     * @template T Extends the PostboyGenericMessage type, representing the type of message
-     * to be recorded and replayed.
-     * @param {MessageType<T>} type The constructor of the message type to be recorded and replayed.
-     * @param {number} [bufferSize=1] The number of recent messages to retain in the ReplaySubject's buffer.
-     * Defaults to 1 if not specified.
-     * @returns The result of invoking the `record` method with the given message type and configured ReplaySubject.
+     * @param type - The constructor of the message type; must declare its own static `ID`.
+     * @param bufferSize - How many past messages to replay to new subscribers; defaults to 1.
+     * @return This registrator, for chaining.
      */
     recordReplay<T extends PostboyGenericMessage>(type: MessageType<T>, bufferSize?: number): PostboyAbstractRegistrator;
     /**
-     * Represents a method that records a specific behavior associated with a message type.
-     * It creates a `BehaviorSubject` initialized with the provided initial message
-     * and associates it with the given message type using the `record` method.
+     * Registers the type with a `BehaviorSubject` seeded with `initial`: every new
+     * subscriber immediately receives the most recent message — the seed itself until
+     * anything is fired. Suited for state-like messages rather than one-off events.
      *
-     * @template T - A type parameter extending `PostboyGenericMessage` that defines the message structure.
-     * @param {MessageType<T>} type - The constructor function of the message type to be recorded.
-     * @param {T} initial - The initial value of the message that will be set in the `BehaviorSubject`.
-     * @returns {void} - This function does not return a value; instead, it modifies the internal state.
+     * @param type - The constructor of the message type; must declare its own static `ID`.
+     * @param initial - The message instance new subscribers receive before any `PostboyService.fire`.
+     * @return This registrator, for chaining.
      */
     recordBehavior<T extends PostboyGenericMessage>(type: MessageType<T>, initial: T): PostboyAbstractRegistrator;
     /**
-     * A function that creates and returns a new generic message recorder for a specific message type.
+     * Registers the type with a plain `Subject`: subscribers only see messages fired after
+     * they subscribed. The default choice for event-like messages.
      *
-     * @template T - A type parameter extending from `PostboyGenericMessage`.
-     * @param {MessageType<T>} type - The constructor for the message type being recorded.
-     * @returns {Subject<T>} A new instance of `Subject<T>` bound to the specified message type.
+     * @param type - The constructor of the message type; must declare its own static `ID`.
+     * @return This registrator, for chaining.
      */
     recordSubject<T extends PostboyGenericMessage>(type: MessageType<T>): this;
 }
 
+/**
+ * The pipeline phase a middleware hook is running for. Each bus verb has its own stage:
+ * `Publish` for `fire`, `Callback` for `fireCallback`, `Execute` for `exec`.
+ */
 declare enum MiddlewareStage {
+    /** `PostboyService.fire` — pub/sub dispatch. */
     Publish = 1,
+    /** `PostboyService.fireCallback` — async request/response dispatch. */
     Callback = 2,
+    /** `PostboyService.exec` — synchronous command execution, including infrastructure messages. */
     Execute = 3
 }
 
+/**
+ * What every middleware hook receives: the running stage plus the message or executor
+ * being processed. Filter by `stage` and `message.id` inside `canHandle`.
+ */
 interface PipelineContext<T extends PostboyMessage = PostboyMessage> {
+    /** The pipeline phase the `before`/`after` hook is running for. */
     stage: MiddlewareStage;
+    /** The fired message or the executed executor. */
     message: T;
 }
 
+/**
+ * The verdict a middleware returns from its `before` hook: let the operation proceed,
+ * or cancel it.
+ */
 declare enum MiddlewareDecisionType {
+    /** Run the operation; the pipeline moves on to the next middleware. */
     Continue = 1,
+    /** Cancel the operation: the bus throws a {@link CancelError} and the `after` hooks are skipped. */
     Interrupt = 2
 }
 
+/** The decision returned by a middleware's `before` hook. */
 interface MiddlewareDecision {
+    /** Whether the operation may proceed; {@link MiddlewareDecisionType.Interrupt} cancels it. */
     type: MiddlewareDecisionType;
 }
 
+/**
+ * Structured information about a middleware cancellation, carried by
+ * {@link CancelError.details}.
+ */
 interface CancelDetails {
+    /** The stage whose `before` hook cancelled the operation. */
     stage: MiddlewareStage;
+    /** Human-readable reason; becomes the `CancelError` message when set. */
     reason?: string;
+    /** `name` of the middleware that returned the interrupt decision. */
     middleware?: string;
+    /** The static `ID` of the cancelled message or executor. */
     messageId?: string;
+    /** Reserved for namespace attribution; not populated by the built-in pipeline. */
     namespace?: string;
 }
 
+/**
+ * The error thrown when a middleware interrupts an operation by returning an interrupt
+ * decision from its `before` hook — the operation does not run.
+ *
+ * Thrown by `PostboyService.fire`, `fireCallback`, and `exec`. Distinguish it from other
+ * errors via `error.name === 'PostboyCancelError'` or `error instanceof CancelError`,
+ * then inspect {@link details} to find the cancelling middleware and stage.
+ */
 declare class CancelError extends Error {
+    /** Structured information about the cancellation. */
     readonly details: CancelDetails;
+    /**
+     * @param details - What was cancelled, where, and why; `details.reason` — or a generated
+     * stage message — becomes the error message.
+     */
     constructor(details: CancelDetails);
 }
 
+/**
+ * A summary of a pipeline run: whether the operation was cancelled, and by whom.
+ *
+ * Kept for middleware implementations that collect their own run reports; the built-in
+ * pipeline surfaces cancellations as a thrown {@link CancelError} instead.
+ */
 type PipelineResult = {
+    /** Whether an `Interrupt` decision stopped the operation. */
     cancelled: boolean;
+    /** `name` of the middleware that cancelled the operation. */
     cancelledBy?: string;
+    /** Why the operation was cancelled. */
     reason?: string;
 };
 
+/**
+ * Execution context of a message — a snapshot of where in a message-causality chain the
+ * current code runs, built by the internal context tracking when it is active.
+ */
 interface PostboyMessageContext {
+    /** Shared by every message of one logical operation; equals the root message's id. */
     correlationId: string;
+    /** The static `ID` of the message currently being processed. */
     currentMessageId: string;
+    /** The `ID` of the message whose handling triggered this one, when nested. */
     parentMessageId?: string;
+    /** How many messages separate this one from the root of the chain. */
     depth: number;
+    /** When the root message of the chain was fired. */
     startedAt: Date;
+    /** Tags accumulated along the chain — the union of the messages' metadata tags. */
     tags?: Set<string>;
 }
 
 /**
- * A class that manages a reactive subscription using a provided Subject and transformation pipe.
- * Offers methods to interact with the subscription, such as emitting data, completing the subscription,
- * and accessing the transformed observable.
+ * The internal pairing of a registered subject with the observable handed out to
+ * subscribers — the pipe, when given, is applied exactly once, here.
  *
- * @template T The type of data managed by the subscription.
+ * Created by the registration paths (`ConnectMessage` and the deprecated `record*`
+ * methods); consumer code never constructs it directly.
+ *
+ * @template T - The message type the stream carries.
  */
 declare class PostboySubscription<T> {
     private subscription;
     private readonly _subscription;
     /**
-     * Constructs an instance of the class with a given subscription and a transformation pipe.
-     *
-     * @param {Subject<T>} subscription - The source Subject that will be transformed.
-     * @param {(s: Subject<T>) => Observable<T>} pipe - A function that applies a transformation to the subscription.
+     * @param subscription - The subject `fire` pushes messages into.
+     * @param pipe - Optional wrapper producing the observable subscribers receive; defaults to the plain subject.
      */
     constructor(subscription: Subject<T>, pipe?: (s: Subject<T>) => Observable<T>);
-    /**
-     * Returns an observable subscription.
-     *
-     * @return {Observable<T>} An observable instance of type T.
-     */
+    /** The observable handed out on every `PostboyService.sub` call — one shared stream for all subscribers. */
     sub(): Observable<T>;
-    /**
-     * Triggers an event by emitting the provided data to all subscribers.
-     *
-     * @param {T} data - The data to emit to the subscribers.
-     * @return {void} - Does not return any value.
-     */
+    /** Pushes a message into the underlying subject, notifying all subscribers synchronously. */
     fire(data: T): void;
-    /**
-     * Completes the subscription, signaling that no further values will be sent.
-     * This is typically used to finalize or clean up resources.
-     * @return {void} This method does not return any value.
-     */
+    /** Completes the underlying subject, ending every subscriber's stream. */
     finish(): void;
 }
 
 /**
- * Abstract base class for defining middleware in a pipeline.
- * Middleware acts on various stages of pipeline execution, allowing operations
- * to be intercepted, modified, or monitored.
+ * Base class for custom middleware — the "customs officers" inspecting everything that
+ * travels through the bus.
+ *
+ * A middleware joins the pipeline via `AddMiddleware` and leaves it via
+ * `RemoveMiddleware`, which also calls {@link dispose}. For every operation the hooks
+ * run per stage (`Publish` for `fire`, `Callback` for `fireCallback`, `Execute` for
+ * `exec` — see {@link MiddlewareStage}): {@link canHandle} is consulted first, then
+ * {@link before} ahead of the operation, then {@link after} once it has finished.
+ * Hooks run for infrastructure messages too — filter with {@link canHandle} if needed.
+ *
+ * Put validation and gating into {@link before}: returning an interrupt decision there
+ * cancels the operation with a {@link CancelError}. Put logging and other side effects
+ * into {@link after}.
+ *
+ * @example
+ * ```ts
+ * class AuthMiddleware extends PostboyMiddleware {
+ *   canHandle(context: PipelineContext): boolean {
+ *     return context.stage === MiddlewareStage.Execute;
+ *   }
+ *
+ *   before(context: PipelineContext): MiddlewareDecision {
+ *     return isAllowed(context.message)
+ *       ? { type: MiddlewareDecisionType.Continue }
+ *       : { type: MiddlewareDecisionType.Interrupt };
+ *   }
+ * }
+ *
+ * postboy.exec(new AddMiddleware(new AuthMiddleware()));
+ * ```
  */
 declare abstract class PostboyMiddleware {
+    /** Identifies the middleware in {@link CancelError} details; defaults to the class name. */
     readonly name: string;
     /**
-     * Creates an instance of a class, optionally assigning a name.
-     *
-     * @param {string} [name] - An optional name to be assigned. If not provided, defaults to the class name.
+     * @param name - Custom name reported on cancellation; defaults to the class name.
      */
     constructor(name?: string);
     /**
-     * Optional filter to skip middleware for unrelated messages/stages.
+     * Decides whether this middleware participates for the given context. Override to
+     * narrow the middleware by stage or message id. Default: handle everything.
      */
     canHandle(_context: PipelineContext): boolean;
     /**
-     * Called before the stage is executed.
-     * Return Interrupt to cancel the operation.
+     * Runs ahead of the operation. Return an interrupt decision
+     * ({@link MiddlewareDecisionType.Interrupt}) to cancel it: the bus then throws a
+     * {@link CancelError}, and the operation and all `after` hooks are skipped.
+     * Default: continue.
      */
     before(_context: PipelineContext): MiddlewareDecision;
     /**
-     * Called after the stage has finished successfully.
-     * `result` is typically set for execute-stage.
+     * Runs after the operation has finished successfully. `result` carries the executor's
+     * return value on the `Execute` stage and is `undefined` on `Publish` and `Callback`.
+     * Default: no-op.
      */
     after(_context: PipelineContext, _result?: unknown): void;
-    /**
-     * Optional cleanup hook.
-     */
+    /** Cleanup hook called on `RemoveMiddleware` and on bus disposal. Default: no-op. */
     dispose(): void;
 }
 
+/**
+ * The middleware pipeline of the bus: keeps the chain in insertion order and drives the
+ * hooks around every operation. Consumer code does not call it directly — middleware is
+ * managed through the `AddMiddleware`/`RemoveMiddleware` messages.
+ */
 declare class PostboyMiddlewareService {
+    /** The middleware chain, in insertion order. */
     protected middlewares: PostboyMiddleware[];
+    /** Appends the middleware to the end of the chain; appending the same instance twice runs its hooks twice. */
     addMiddleware(middleware: PostboyMiddleware): void;
+    /** Removes the middleware by identity and calls its `dispose()` hook; unknown instances are ignored. */
     removeMiddleware(middleware: PostboyMiddleware): void;
+    /** Disposes every middleware in the chain and empties it. */
     dispose(): void;
+    /**
+     * Runs the `before` hooks for the stage, consulting `canHandle` on each middleware.
+     * Stops and throws {@link CancelError} as soon as one returns an interrupt decision.
+     *
+     * @throws CancelError With the stage, middleware name, and message id of the interruption.
+     */
     before<T extends PostboyMessage>(stage: MiddlewareStage, message: T): void;
+    /** Runs the `after` hooks for the stage, passing the executor result when there is one. */
     after<T extends PostboyMessage, R = unknown>(stage: MiddlewareStage, message: T, result?: R): void;
+    /** `before` hooks for the `Publish` stage (`PostboyService.fire`). */
     beforePublish(message: PostboyMessage): void;
+    /** `after` hooks for the `Publish` stage (`PostboyService.fire`). */
     afterPublish(message: PostboyMessage): void;
+    /** `before` hooks for the `Callback` stage (`PostboyService.fireCallback`). */
     beforeCallback(message: PostboyMessage): void;
+    /** `after` hooks for the `Callback` stage — run on every emitted result value. */
     afterCallback(message: PostboyMessage, result?: unknown): void;
+    /** `before` hooks for the `Execute` stage (`PostboyService.exec`). */
     beforeExecute<T>(message: PostboyExecutor<T>): void;
+    /** `after` hooks for the `Execute` stage, receiving the executor's return value. */
     afterExecute<T>(message: PostboyExecutor<T>, result: T): void;
     private buildContext;
     private throwIfCancelled;
 }
 
 /**
- * The PostboyMessageStore is a utility class for managing message subscriptions and executors.
- * It provides functionality to register, retrieve, and unregister subscription-based messages and executors.
+ * The registry behind the bus: message subscriptions and executor handlers keyed by
+ * their static `ID`, plus completion callbacks for fired callback messages. Consumer
+ * code reaches it only through `PostboyService` and the infrastructure messages.
  */
 declare class PostboyMessageStore {
     protected messages: Map<string, PostboySubscription<any>>;
     protected executors: Map<string, (e: PostboyExecutor<any>) => any>;
     protected callbacks: Map<string, (() => void)[]>;
+    /**
+     * Registers a message subscription under the id, logging a warning and overriding
+     * when the id is already taken.
+     */
     registerMessage(id: string, sub: PostboySubscription<any>): void;
+    /**
+     * Registers an executor handler under the id, logging a warning and overriding
+     * when the id is already taken.
+     */
     registerExecutor(id: string, executor: (e: PostboyExecutor<any>) => any): void;
+    /** Records a callback completing the message's result when its type is unregistered or the bus disposed. */
     callbackFired(message: PostboyCallbackMessage<any>): void;
+    /**
+     * @param id - The static `ID` the subscription was registered under.
+     * @param name - Used only in the error message.
+     * @throws Error When no message is registered under the id.
+     */
     getMessage(id: string, name: string): PostboySubscription<any>;
+    /**
+     * @param id - The static `ID` the handler was registered under.
+     * @throws Error When no executor is registered under the id.
+     */
     getExecutor<T>(id: string): (e: PostboyExecutor<T>) => T;
+    /**
+     * Removes an id completely: completes its subscription stream, runs the recorded
+     * completion callbacks (completing fired callback results), and deletes the message,
+     * executor, and callback entries.
+     */
     unregister(id: string): void;
+    /**
+     * Tears the store down: unregisters every message, runs the remaining callbacks, and
+     * clears all maps — including the infrastructure handlers, so the bus must be
+     * re-created to work again.
+     */
     dispose(): void;
 }
 
 /**
- * Represents a store for managing namespaces in the Postboy system.
- * Provides functionality to add, eliminate, and dispose namespaces.
+ * The registry of namespaces behind `AddNamespace`/`EliminateNamespace`: maps each name
+ * to the registrator managing its registrations.
  */
 declare class PostboyNamespaceStore {
     private spaces;
     /**
-     * Adds a new space or retrieves an existing one if it already exists.
+     * Returns the registrator of the given name, creating it on first use.
      *
-     * @param {string} space - The name of the space to add or retrieve.
-     * @param {PostboyService} postboy - The PostboyService instance used to create a namespace registrator.
-     * @return {PostboyAbstractRegistrator} The registrator associated with the specified space.
+     * @param space - The unique namespace name.
+     * @param postboy - The bus the new registrator executes its registration messages on.
+     * @return The registrator of the namespace — the existing one when the name is known.
      */
     addSpace(space: string, postboy: PostboyService): PostboyAbstractRegistrator;
     /**
-     * Removes a specified space from the spaces collection if it exists.
-     * If the space exists, it will be deleted after invoking its down method.
+     * Tears the namespace down — `down()` on its registrator, disconnecting everything it
+     * recorded — and removes it. Unknown names are ignored.
      *
-     * @param {string} space - The name of the space to be removed.
-     * @return {void} This method does not return a value.
+     * @param space - The namespace name to remove.
      */
     eliminateSpace(space: string): void;
-    /**
-     * Disposes of the current instance by performing cleanup operations.
-     * Iterates through all spaces, performs a "down" operation on each,
-     * and then clears the collection of spaces.
-     *
-     * @return {void} No return value.
-     */
+    /** Tears down every namespace and clears the store; called by `PostboyService.dispose()`. */
     dispose(): void;
 }
 
+/**
+ * Assembles the internal collaborators of a `PostboyService`: its middleware pipeline,
+ * message store, and namespace store. The default factories create fresh instances with
+ * no shared state; substitute stubs (e.g. in tests) by passing a custom resolver to the
+ * `PostboyService` constructor.
+ */
 declare class PostboyDependencyResolver {
-    /**
-     * Retrieves an instance of the PostboyMiddlewareService.
-     *
-     * This function initializes and returns a new instance of the
-     * PostboyMiddlewareService, which can be used to configure and manage
-     * middleware for a specific module or application.
-     *
-     * @returns {PostboyMiddlewareService} A new instance of PostboyMiddlewareService.
-     */
+    /** Factory for the bus middleware pipeline — one fresh instance per call. */
     getMiddlewareService: () => PostboyMiddlewareService;
-    /**
-     * A function that instantiates and returns a new instance of PostboyMessageStore.
-     *
-     * This function serves as a factory method for creating instances
-     * of the PostboyMessageStore class.
-     *
-     * @returns {PostboyMessageStore} A new instance of the PostboyMessageStore class.
-     */
+    /** Factory for the message registry — one fresh instance per call. */
     getMessageStore: () => PostboyMessageStore;
-    /**
-     * Creates and initializes a new instance of PostboyNamespaceStore using the provided PostboyService instance.
-     *
-     * @function getNamespaceStore
-     * @returns {PostboyNamespaceStore} A new instance of PostboyNamespaceStore associated with the given PostboyService.
-     */
+    /** Factory for the namespace registry — one fresh instance per call. */
     getNamespaceStore: () => PostboyNamespaceStore;
 }
 
+/**
+ * The central message bus of the postboy library.
+ *
+ * All routing is keyed by the static `ID` declared on message and executor classes —
+ * not by class identity. Three kinds of traffic are supported:
+ * - pub/sub: register a message type with a `ConnectMessage`, subscribe via {@link sub},
+ *   dispatch via {@link fire};
+ * - synchronous commands: register a handler with a `ConnectExecutor`/`ConnectHandler`,
+ *   invoke it via {@link exec};
+ * - async request/response: a {@link PostboyCallbackMessage} fired via {@link fireCallback}.
+ *
+ * Every bus mutation — registration, middleware, locking, namespaces — is performed by
+ * executing one of the infrastructure messages via {@link exec}; the constructor wires
+ * their handlers automatically.
+ *
+ * @example
+ * ```ts
+ * class PingMessage extends PostboyGenericMessage {
+ *   static readonly ID = 'app.ping';
+ *   constructor(public text: string) {
+ *     super();
+ *   }
+ * }
+ *
+ * const postboy = new PostboyService();
+ * postboy.exec(new ConnectMessage(PingMessage, new Subject<PingMessage>()));
+ * postboy.sub(PingMessage).subscribe((m) => console.log(m.text));
+ * postboy.fire(new PingMessage('hello'));
+ * ```
+ */
 declare class PostboyService {
+    /** Ids of message types locked via `LockMessage`; {@link fire} and {@link fireCallback} skip their delivery. */
     protected locked: Set<string>;
     private middleware;
     private store;
     private namespaceStore;
     private dependencyResolver;
+    /**
+     * Creates a bus and registers handlers for all infrastructure messages.
+     *
+     * @param resolver - Supplies the internal collaborators (middleware pipeline, message store, namespace store).
+     * Defaults to a `PostboyDependencyResolver` with fresh instances; pass a custom one to inject test doubles.
+     */
     constructor(resolver?: PostboyDependencyResolver);
+    /** Registers handlers for the infrastructure messages — the only way to mutate the bus. */
     private registerInfrastructureMessages;
     /**
-     * Fires a registered event and passes the message to its subscribers.
+     * Publishes a message to all current subscribers of its type.
+     *
+     * Runs the `Publish`-stage middleware `before` hooks, delivers the message to the
+     * registered subject, then runs the `after` hooks. If the type is locked (see
+     * `LockMessage`), delivery is silently skipped — subscribers receive nothing — but
+     * both middleware hooks still run.
      *
-     * @param {PostboyGenericMessage} message - The message object containing the event data.
-     * @return {void} This method does not return a value.
-     * @throws {Error} Throws an error if no registered event is found for the provided message ID.
+     * @param message - The message instance to publish.
+     * @throws CancelError When a `Publish`-stage middleware returns an interrupt decision.
+     * @throws Error When no message of this type is registered; the `after` hooks are then skipped.
      */
     fire(message: PostboyGenericMessage): void;
     /**
-     * Triggers a callback function associated with a given message.
-     *
-     * @param {PostboyCallbackMessage<T>} message - The message object used to trigger the callback.
-     * It contains details about the event and result subscription.
-     * @param {(e: T) => void} [action] - Optional callback function to execute when the result of the message is emitted.
-     * @return {void} This method does not return any value.
+     * Fires a {@link PostboyCallbackMessage} and returns an observable of its result (async request/response).
+     *
+     * The responder side subscribes to the message type via {@link sub} and produces the
+     * result with `message.next(...)` / `message.finish(...)`.
+     *
+     * Dispatch semantics depend on `action`:
+     * - with `action`, the message is dispatched immediately and `action` is invoked once
+     *   per emitted result value, independently of any subscriptions to the returned
+     *   observable;
+     * - without `action`, dispatch is lazy: it happens on the first subscription to the
+     *   returned observable.
+     *
+     * `Callback`-stage middleware `before` hooks run at call time; `after` hooks run on
+     * every emitted result value. If the type is locked, dispatch is silently skipped.
+     * The result observable completes when the message type is disconnected
+     * (see `DisconnectMessage`) or the bus is disposed.
+     *
+     * @param message - The callback message carrying the request.
+     * @param action - Optional callback invoked once per emitted result value.
+     * @return An observable emitting the result values produced by the responder.
+     * @throws CancelError When a `Callback`-stage middleware returns an interrupt decision.
+     * @throws Error When no message of this type is registered; thrown synchronously, before any dispatch.
+     *
+     * @example
+     * ```ts
+     * postboy.exec(new ConnectMessage(FetchDataMessage, new Subject<FetchDataMessage>()));
+     * // responder: produces the result
+     * postboy.sub(FetchDataMessage).subscribe((m) => m.finish('payload'));
+     * // requester: consumes it
+     * postboy.fireCallback(new FetchDataMessage()).subscribe((payload) => console.log(payload));
+     * ```
      */
     fireCallback<T>(message: PostboyCallbackMessage<T>, action?: (e: T) => void): Observable<T>;
     /**
-     * Executes the provided executor function and returns its result.
+     * Synchronously executes a registered executor command and returns its result — never `await` it.
+     *
+     * Runs the `Execute`-stage middleware `before` hooks, invokes the handler registered
+     * for the executor's static `ID`, then the `after` hooks with the result. For async
+     * results use a {@link PostboyCallbackMessage} with {@link fireCallback} instead.
      *
-     * @param {PostboyExecutor<T>} executor The executor to be executed, which includes its identifier and logic.
-     * @return {T} The resulting output from the executed executor function.
-     * @throws {Error} If the specified executor is not registered.
+     * This is also the entry point for the infrastructure messages themselves
+     * (`ConnectMessage`, `AddMiddleware`, ...), so middleware sees them on the `Execute`
+     * stage too — filter them out with `canHandle` if needed.
+     *
+     * @param executor - The executor instance carrying the command.
+     * @return Whatever the registered handler returns.
+     * @throws CancelError When an `Execute`-stage middleware returns an interrupt decision.
+     * @throws Error When no handler is registered for this executor type.
      */
     exec<T>(executor: PostboyExecutor<T>): T;
     /**
-     * Subscribes to a specific message type and returns an observable of that type.
+     * Returns the observable stream of a registered message type.
+     *
+     * Every call returns a view of the one registered subject — or of its pipe, when the
+     * type was registered via `ConnectMessage` with a pipe. It is an `Observable`, not a
+     * `Subject`: never call `next` on it, emit via {@link fire}. Subscribers only receive
+     * messages fired after their subscription, unless the type was registered with a
+     * replay or behavior subject.
      *
-     * @param type The constructor function of the type that extends PostboyGenericMessage.
-     * @return An Observable of the specified generic message type.
+     * @param type - The constructor of the message type; must declare its own static `ID`.
+     * @throws Error When the class has no static `ID` or no message of this type is registered.
      */
     sub<T extends PostboyGenericMessage>(type: MessageType<T>): Observable<T>;
     /**
-     * Subscribes to a specific message type and automatically unsubscribes after receiving the first message.
+     * Like {@link sub}, but completes right after the first message of the type arrives.
      *
-     * @param type The type of message to subscribe to.
-     * @return An observable that emits the first message of the specified type and then completes.
+     * @param type - The constructor of the message type; must declare its own static `ID`.
+     * @return An observable that emits one message and then completes.
+     * @throws Error When the class has no static `ID` or no message of this type is registered.
      */
     once<T extends PostboyGenericMessage>(type: MessageType<T>): Observable<T>;
     /**
-     * Registers a given message type and its associated subject subscription with the system.
+     * Registers a message type with the given subject.
+     *
+     * Re-registering the same `ID` logs a warning and overrides the previous registration.
      *
      * @deprecated The method should be replaced with firing {@link ConnectMessage} message.
-     * @param type The constructor function of the message type that extends the PostboyGenericMessage.
-     * @param sub The Subject instance for the provided message type, used for managing subscriptions.
-     * @return {void} No return value.
+     * @param type - The constructor of the message type; must declare its own static `ID`.
+     * @param sub - The subject subscribers will observe.
      */
     record<T extends PostboyGenericMessage>(type: MessageType<T>, sub: Subject<T>): void;
     /**
-     * Registers a generic message type with a Subject and a transformation pipe.
+     * Registers a message type whose stream is transformed by a pipe before reaching subscribers.
+     *
+     * Re-registering the same `ID` logs a warning and overrides the previous registration.
      *
      * @deprecated The method should be replaced with firing {@link ConnectMessage} message.
-     * @param {MessageType<T>} type - The constructor of the message type being registered.
-     * @param {Subject<T>} sub - The Subject instance used to handle incoming messages of the specified type.
-     * @param {(s: Subject<T>) => Observable<T>} pipe - A function that applies a transformation or processing logic to the Subject and returns an Observable.
-     * @return {void} No return value.
+     * @param type - The constructor of the message type; must declare its own static `ID`.
+     * @param sub - The subject subscribers will observe.
+     * @param pipe - Wraps the subject into the observable handed out by {@link sub}, e.g. to apply operators.
      */
     recordWithPipe<T extends PostboyGenericMessage>(type: MessageType<T>, sub: Subject<T>, pipe: (s: Subject<T>) => Observable<T>): void;
     /**
-     * Registers an executor for a specified message type.
+     * Registers a synchronous handler for an executor type, invoked by {@link exec}.
+     *
+     * Re-registering the same `ID` logs a warning and overrides the previous registration.
      *
      * @deprecated The method should be replaced with firing {@link ConnectExecutor} message.
-     * @param {MessageType<E>} type - The message type for which the executor is being registered.
-     * @param {(e: E) => T} exec - The executor function that will handle messages of the specified type.
-     * @return {void} This method does not return any value.
+     * @param type - The constructor of the executor class; must declare its own static `ID`.
+     * @param exec - Called with the executor instance on every {@link exec} of this type.
      */
     recordExecutor<E extends PostboyExecutor<T>, T>(type: MessageType<E>, exec: (e: E) => T): void;
     /**
-     * Registers a handler for a specific executor type.
+     * Registers a {@link PostboyExecutionHandler} instance for an executor type, invoked by {@link exec}.
+     *
+     * Re-registering the same `ID` logs a warning and overrides the previous registration.
      *
      * @deprecated The method should be replaced with firing {@link ConnectHandler} message.
-     * @param executor The constructor of the executor class that extends `PostboyExecutor<R>`.
-     * @param handler An instance of `PostboyExecutionHandler<R, E>` that defines the logic for handling the executor.
-     * @return void
+     * @param executor - The constructor of the executor class; must declare its own static `ID`.
+     * @param handler - Its `handle` method is called with the executor instance on every {@link exec} of this type.
      */
     recordHandler<E extends PostboyExecutor<R>, R>(executor: new (...args: any[]) => E, handler: PostboyExecutionHandler<R, E>): void;
     /**
-     * Disposes of resources and cleans up any internal components or stores associated with the instance.
-     * This method ensures that all resources are properly released to avoid memory leaks.
+     * Tears down the whole bus: calls `down()` on every namespace registrator (completing
+     * everything they registered), completes all remaining message subscriptions and
+     * callback results, and disposes every middleware.
      *
-     * @return {void} This method does not return a value.
+     * Infrastructure registrations are re-created only by constructing a new service.
      */
     dispose(): void;
 }
 
 /**
- * Represents a {@link PostboyMiddleware} addition operation for Postboy.
- * This class extends the functionality of the PostboyExecutor to add middleware to the processing chain.
+ * Infrastructure message that appends a {@link PostboyMiddleware} to the pipeline.
+ *
+ * Executing it via `PostboyService.exec` adds the middleware to the end of the chain:
+ * hooks then run for every stage its `canHandle` accepts, in insertion order. Adding
+ * the same instance twice makes its hooks run twice.
  *
- * The middleware to be added is provided during instantiation.
+ * @example
+ * ```ts
+ * postboy.exec(new AddMiddleware(new LoggingMiddleware()));
+ * ```
  */
 declare class AddMiddleware extends PostboyExecutor<void> {
     middleware: PostboyMiddleware;
     static readonly ID = "0a8cfe0a-6193-4082-8440-d0793367b21d";
     /**
-     * Initializes a new instance of the class with the specified middleware.
-     *
-     * @param {PostboyMiddleware} middleware - The {@link PostboyMiddleware} to be used for processing.
+     * @param middleware - The middleware instance to append.
      */
     constructor(middleware: PostboyMiddleware);
 }
 
 /**
- * Represents a class responsible for removing {@link PostboyMiddleware} in execution flow.
- * This class extends PostboyExecutor and operates with a void return type.
+ * Infrastructure message that removes a {@link PostboyMiddleware} from the pipeline.
+ *
+ * Executing it via `PostboyService.exec` drops the instance from the chain — matched by
+ * identity, not by name or class — and calls its `dispose()` hook. Pass the very same
+ * instance that was added via `AddMiddleware`.
  */
 declare class RemoveMiddleware extends PostboyExecutor<void> {
     middleware: PostboyMiddleware;
     static readonly ID = "c25c708c-53c9-498d-a28b-936fbaf68b91";
     /**
-     * Constructs an instance of the class with the specified middleware.
-     *
-     * @param {PostboyMiddleware} middleware - The {@link PostboyMiddleware} instance to be removed.
+     * @param middleware - The middleware instance previously added via `AddMiddleware`.
      */
     constructor(middleware: PostboyMiddleware);
 }
 
 /**
- * Locks a specific message type to prevent firing of them.
+ * Infrastructure message that locks a message type on the bus.
  *
- * This class is used to handle operations associated with locking mechanisms
- * for a specified message type.
+ * Executing it via `PostboyService.exec` adds the type's static `ID` to the locked set:
+ * subsequent `fire()` and `fireCallback()` calls for that type silently skip delivery —
+ * subscribers receive nothing — while middleware `before`/`after` hooks still run and
+ * `exec()` is unaffected. Registration stays intact, so unlocking resumes delivery
+ * immediately. Treat a locked message as a no-op, not an error.
  *
- * @template T - A type that extends {@link PostboyGenericMessage}.
+ * @example
+ * ```ts
+ * postboy.exec(new LockMessage(PingMessage)); // PingMessage stops being delivered
+ * postboy.exec(new UnlockMessage(PingMessage)); // delivery resumes
+ * ```
  */
 declare class LockMessage<T extends PostboyGenericMessage> extends PostboyExecutor<void> {
     type: MessageType<T>;
     static readonly ID = "477df3e2-1f99-4476-9a3b-afd1fa426436";
     /**
-     * Constructs an instance of the class with the specified message type.
-     *
-     * @param {MessageType<T>} type - The type of the message to be used for the instance.
+     * @param type - The constructor of the message type to lock.
      */
     constructor(type: MessageType<T>);
 }
 
 /**
- * A specialized executor that handles the unlocking process for messages of a specified type.
- * Unlocks a previously locked message, making it available for processing again.
+ * Infrastructure message that unlocks a message type locked by `LockMessage`.
  *
- * @template T - The type parameter extending {@link PostboyGenericMessage}, representing the message type handled by the executor.
- * @extends {PostboyExecutor<void>}
+ * Executing it via `PostboyService.exec` removes the type's static `ID` from the locked
+ * set, so `fire()` and `fireCallback()` deliver it again. Unlocking a type that was
+ * never locked changes nothing.
  */
 declare class UnlockMessage<T extends PostboyGenericMessage> extends PostboyExecutor<void> {
     type: MessageType<T>;
     static readonly ID = "d71d25e3-90ac-4009-b972-9e6c6b05611e";
     /**
-     * Creates an instance of the class with the specified message type.
-     *
-     * @param {MessageType<T>} type - The message type for this instance.
+     * @param type - The constructor of the message type to unlock.
      */
     constructor(type: MessageType<T>);
 }
 
 /**
- * AddNamespace is a class that extends the PostboyExecutor with a specific implementation
- * for adding namespaces to a PostboyService instance.
+ * Infrastructure message that creates — or returns the existing — registrator of a
+ * namespace.
+ *
+ * Executing it via `PostboyService.exec` registers the given name in the namespace
+ * store and returns the {@link PostboyAbstractRegistrator} for it: record messages and
+ * executors on that registrator, then tear them all down at once with
+ * `EliminateNamespace` (or the registrator's own `down()`). Executing it again with the
+ * same name returns the same registrator without recreating it.
  *
- * This class is identified uniquely by its static ID property for tracking and referencing purposes.
+ * @example
+ * ```ts
+ * const reg = postboy.exec(new AddNamespace('feature-a'));
+ * reg.recordSubject(PingMessage);
+ * // later: postboy.exec(new EliminateNamespace('feature-a')); — disconnects everything recorded
+ * ```
  */
 declare class AddNamespace extends PostboyExecutor<PostboyAbstractRegistrator> {
     space: string;
     static readonly ID = "6d1a6f7d-6b6e-4c4d-8af8-9cc9a32e850c";
     /**
-     * Creates an instance of the class with the specified space identifier.
-     *
-     * @param {string} space - The identifier for the space.
+     * @param space - The unique name of the namespace.
      */
     constructor(space: string);
 }
 
 /**
- * Represents an executor that eliminates a specific namespace.
- * This class extends the PostboyExecutor with a void return type.
+ * Infrastructure message that tears down a namespace created by `AddNamespace`.
+ *
+ * Executing it via `PostboyService.exec` calls `down()` on the namespace's registrator —
+ * disconnecting every message and executor it recorded — and removes the namespace.
+ * Eliminating an unknown name changes nothing.
  */
 declare class EliminateNamespace extends PostboyExecutor<void> {
     space: string;
     static readonly ID = "03bb03bb-53e0-4b74-9aad-64d5c54a8972";
     /**
-     * Creates an instance of the class with the specified space value.
-     *
-     * @param {string} space - The string value representing the space configuration.
+     * @param space - The name the namespace was created with.
      */
     constructor(space: string);
 }
 
 /**
- * Represents a connection handler that extends the PostboyExecutor class.
+ * Infrastructure message that registers a {@link PostboyExecutionHandler} for an
+ * executor type.
  *
- * This class encapsulates logic associated with executing a handler in a structured way.
- * It is generic and operates on the provided executor and handler types.
+ * Executing it via `PostboyService.exec` binds the executor class's static `ID` to the
+ * handler: every subsequent `exec` of that type calls `handler.handle(...)` and returns
+ * its result. Re-registering the same `ID` logs a warning and overrides the previous
+ * registration. The non-deprecated replacement for `PostboyService.recordHandler`.
  *
- * Type Parameters:
- *   E - Represents an extension of the PostboyExecutor class with a specific type parameter R.
- *   R - Represents the type of the result that the executor is expected to operate on.
+ * @template E - The executor type being served.
+ * @template R - The result its handler returns.
  */
 declare class ConnectHandler<E extends PostboyExecutor<R>, R> extends PostboyExecutor<void> {
     executor: new (...args: any[]) => E;
     handler: PostboyExecutionHandler<R, E>;
     static readonly ID = "bf618cea-6f32-417c-9548-8eafe937378b";
     /**
-     * Constructs an instance of the class.
-     *
-     * @param {new (...args: any[]) => E} executor - A constructor function for the executor object.
-     * @param {PostboyExecutionHandler<R, E>} handler - A handler that processes the execution logic.
+     * @param executor - The constructor of the executor class; must declare its own static `ID`.
+     * @param handler - The handler whose `handle` method receives the executor.
      */
     constructor(executor: new (...args: any[]) => E, handler: PostboyExecutionHandler<R, E>);
 }
 
 /**
- * Registers an executor that connects to a specific type of message handler.
- * This class extends the functionality of `PostboyExecutor` and is designed to manage
- * the execution of a handler defined by a specific message type and an execution function.
+ * Infrastructure message that registers a synchronous handler for an executor type.
  *
- * @template E The type of the executor extending {@link PostboyExecutor}.
- * @template T The return type of the execution function.
+ * Executing it via `PostboyService.exec` binds the type's static `ID` to the given
+ * function: every subsequent `exec` of that executor type invokes it and returns its
+ * result. Re-registering the same `ID` logs a warning and overrides the previous
+ * registration. The non-deprecated replacement for `PostboyService.recordExecutor`.
  *
- * @extends {PostboyExecutor<void>}
+ * @template E - The executor type being registered.
+ * @template T - The result its handler returns.
  */
 declare class ConnectExecutor<E extends PostboyExecutor<T>, T> extends PostboyExecutor<void> {
     type: MessageType<E>;
     exec: (e: E) => T;
     static readonly ID = "cb80e8ad-b68c-4b2d-8c44-617ea6017cb3";
     /**
-     * Constructs an instance of the class with the specified type and execution function.
-     *
-     * @param {MessageType<E>} type - The type of the message.
-     * @param {(e: E) => T} exec - The function to be executed with the input of type E that returns a value of type T.
+     * @param type - The constructor of the executor class; must declare its own static `ID`.
+     * @param exec - The handler invoked with the executor instance on every `exec` of this type.
      */
     constructor(type: MessageType<E>, exec: (e: E) => T);
 }
 
 /**
- * Represents a message signaling a disconnection event. This class is used
- * within the framework to manage and process disconnection notifications.
- * Extends the {@link PostboyExecutor} base class.
+ * Infrastructure message that unregisters a message or executor type from the bus.
  *
- * @extends {PostboyExecutor<void>}
+ * Executing it via `PostboyService.exec` completes the registered stream (ending every
+ * subscriber's subscription), runs the registered completion callbacks — in particular,
+ * it completes the result of a fired callback message — and forgets the `ID`, so
+ * further `fire`, `sub`, and `exec` for it throw until it is registered again. This is
+ * the teardown primitive behind `PostboyAbstractRegistrator.down()`.
  */
 declare class DisconnectMessage extends PostboyExecutor<void> {
     messageId: string;
     static readonly ID = "94579e43-5bc9-4517-bcda-b595bcda1ae7";
     /**
-     * Creates an instance of the class with the specified message identifier.
-     *
-     * @param {string} messageId - The unique identifier for the message.
+     * @param messageId - The static `ID` of the message or executor type to remove — not an instance id.
      */
     constructor(messageId: string);
 }
 
 /**
- * Represents a message that facilitates connection functionality
- * within the application's messaging system.
+ * Infrastructure message that registers a pub/sub message type on the bus.
  *
- * @template T - A type that extends {@link PostboyGenericMessage}, representing
- * the structure of the message being handled.
+ * Executing it via `PostboyService.exec` binds the type's static `ID` to the given
+ * subject: `sub()` and `once()` start returning its (piped) stream, and `fire()`
+ * delivers into it. Re-registering the same `ID` logs a warning and overrides the
+ * previous registration. The non-deprecated replacement for the `PostboyService.record*`
+ * methods.
  *
- * @extends PostboyExecutor<void>
+ * @example
+ * ```ts
+ * postboy.exec(new ConnectMessage(PingMessage, new Subject<PingMessage>()));
+ * // with a pipe — subscribers see the transformed stream
+ * postboy.exec(new ConnectMessage(PingMessage, new Subject<PingMessage>(), (s) => s.pipe(share())));
+ * ```
  */
 declare class ConnectMessage<T extends PostboyGenericMessage> extends PostboyExecutor<void> {
     type: MessageType<T>;
@@ -691,11 +1012,9 @@ declare class ConnectMessage<T extends PostboyGenericMessage> extends PostboyExe
     pipe?: ((s: Subject<T>) => Observable<T>) | undefined;
     static readonly ID = "aa03a192-bdc7-402d-9f2f-bf3748229ea2";
     /**
-     * Constructs a new instance of the class.
-     *
-     * @param {MessageType<T>} type - The type of the message.
-     * @param {Subject<T>} sub - The subject to be used for message handling.
-     * @param {(s: Subject<T>) => Observable<T>} [pipe] - An optional function to transform the subject.
+     * @param type - The constructor of the message type; must declare its own static `ID`.
+     * @param sub - The subject the message type is served from.
+     * @param pipe - Optional wrapper producing the observable subscribers receive, e.g. to apply operators.
      */
     constructor(type: MessageType<T>, sub: Subject<T>, pipe?: ((s: Subject<T>) => Observable<T>) | undefined);
 }