Registration & Execution

An executor must be registered before it can be executed. Postboy offers two registration models: direct function and handler‑based. Both associate the executor’s identity with its implementation.

Once registered, execution is done through postboy.exec(…), which returns the typed result synchronously.

1. Direct function registration

Use ConnectExecutor to register a plain function. This is ideal for lightweight operations or thin wrappers around existing logic.

Registration of a message

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

export class FormatDateExecutor extends PostboyExecutor<string> {
  static readonly ID = 'date.format';

  constructor(public readonly date: Date) {
    super();
  }
}

// Register during application bootstrap
postboy.exec(new ConnectExecutor(FormatDateExecutor, (executor) => {
  return Intl.DateTimeFormat('en-US').format(executor.date);
}));

Execution of a message

const formatted = postboy.exec(new FormatDateExecutor(new Date()));
console.log(formatted); // "4/23/2026"

2. Handler‑based registration

For complex operations, place the logic in a dedicated handler class that extends PostboyExecutionHandler<T, E>. Then register it with ConnectHandler.

Handler definition

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

export class RefreshCacheExecutor extends PostboyExecutor<boolean> {
  static readonly ID = 'cache.refresh';

  constructor(public readonly scope: string) {
    super();
  }
}

class RefreshCacheHandler extends PostboyExecutionHandler<boolean, RefreshCacheExecutor> {
  handle(executor: RefreshCacheExecutor): boolean {
// complex multi-step logic
    return cacheService.refresh(executor.scope);
  }
}

Registration

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

postboy.exec(new ConnectHandler(RefreshCacheExecutor, new RefreshCacheHandler()));

Execution

const success = postboy.exec(new RefreshCacheExecutor('users'));
console.log(success); // true

3. Choosing a registration model

Criterion	Direct function (`ConnectExecutor`)	Handler class (`ConnectHandler`)
Boilerplate	Minimal	Moderate
Best for	One‑liners, simple wrappers	Complex logic, multi‑step processes
Unit testing	Test the function directly	Test the handler class in isolation
Separation of concerns	Logic lives near registration	Logic isolated in a separate class

Both models produce the same runtime behaviour. Pick the one that keeps your codebase readable.

4. Infrastructure use‑case

Postboy ships with built‑in executors for bus management. These are registered and executed using the same mechanism.

// Register a new message type
postboy.exec(new ConnectMessage(OrderPlacedEvent, new Subject<OrderPlacedEvent>()));

// Register a callback handler
postboy.exec(new ConnectHandler(GetUserQuery, new GetUserQueryHandler()));

These infrastructure executors are not special — they follow the same contract and lifecycle as any other executor.

5. Summary

Registration is mandatory; use ConnectExecutor or ConnectHandler.
Execution is synchronous and returns the typed result immediately.
Choose direct registration for simple logic, handler classes for complex operations.
Infrastructure operations are just regular executors.

24 апреля 2026