event-dispatching

✨ This package is a modernized and extended version of pleerock/event-dispatch, refactored for personal use and better extensibility.

In-process application event bus of the server. Domain modules declare subscribers with decorators, services dispatch events through AbstractService.eventDispatching, and the dispatching calls the matching subscriber methods, resolved through the Inversify container.

It is not a queue: no persistence, retry, timeout, transaction or cross-process delivery. Deferred or retryable work belongs to the scheduler / workflows. Events only reach listeners of the same Node.js process.

Public API

| Export | Kind | Status | | --- | --- | --- | | event_subscriber() (aliases eventSubscriber, EventSubscriber) | class decorator | stable | | on(event \| events, options?) (alias On) | method decorator | stable | | EventDispatching: dispatch, asyncDispatch | service | stable | | EventDispatching: on, once, attach, detach, remove, detachAll, getActiveListeners | runtime listeners | stable, used in tests | | TYPES.EventDispatching, TYPES.MetadataRegistry | DI tokens | stable | | MetadataRegistry: init, clear, add*/has*Metadata, getEventListeners | registry | stable, internal use | | MetadataRegistry: getAllHandlers, findAllEventsHandlersByEventName | registry | deprecated | | EventMap, EventOptions, EventSubscriberOptions, IEventListenerDescriptor, IEventMetadata, ISubscriberMetadata, IEventSubscriber, IEventsHandler | types | stable (IEventSubscriber, IEventsHandler: legacy) | | DECORATOR_EVENT_SUBSCRIBER_META_KEY, DECORATOR_ON_META_KEY | metadata keys | stable | | isEmpty(value) | utility (defines which dispatch results are kept) | stable, kept for compatibility | | default export bootstrap(app), module | module entry | stable (loaded through app/modules.json) |

Everything is exported from the package root; there are no deep import paths.

Usage

1. Events and payloads (in the domain module)

Each module owns its event names and payload types. Event names are plain strings ("<module_snake>.<aggregate>.<event>"); they may be stored or logged, so never rename them.

export class UserEvents {
    static readonly USER_CREATED = "app_auth.user.created";
}

export interface UserCreatedEvent {
    user: User;
}

2. A subscriber

import { inject, injectable } from "inversify";
import { event_subscriber, on } from "event-dispatching";
import { AbstractService } from "app-common";

@injectable()
@event_subscriber()
export class CMSContentUserEventSubscriber extends AbstractService {

    constructor(@inject(TYPES.PageManager) private readonly _pageManager: PageManager) {
        super("cms_content.UserEventSubscriber");
    }

    @on(UserEvents.USER_CREATED)
    public async onUserCreated(event: UserCreatedEvent): Promise<void> {
        await this._pageManager.createDefaultPages(event.user);
    }

    // One method, several events
    @on([UserEvents.USER_UPDATED, UserEvents.USER_DELETED])
    public async onUserChanged(event: UserCreatedEvent): Promise<void> { /* ... */ }
}

• @injectable() is required: the subscriber is resolved through the container.
• Bind it in the module (options.bind(TYPES.XSubscriber).to(XSubscriber)), as the other modules do.
• The file must be imported by the module (it is, through the binding), so that its decorators run before the application initializes the modules.
• Only instance methods declared on the subscriber class are listeners. @on() on a static method, an accessor, or with an empty / non-string event name throws a TypeError when the class is defined. Stacked @on() decorators on one method add up.
• @on() methods of a class without @event_subscriber() are ignored. Inherited @on() methods are not listeners of the subclass: decorate the subclass method too.
• EventOptions.authRoles is stored but not read by the dispatching.

3. Dispatching

// In any AbstractService subclass
this.eventDispatching.dispatch(UserEvents.USER_CREATED, { user });

// Await the listeners and read their results
const results = await this.eventDispatching.asyncDispatch(OAuth2Events.OAUTH2_EXPIRED, { oAuth2 });

Outside AbstractService: container.get<EventDispatching>(TYPES.EventDispatching).

Dispatch guarantees

| | dispatch() | asyncDispatch() | | --- | --- | --- | | Returns | after every listener has been called | a promise, after every listener has settled | | Async listeners | started, not awaited (fire and forget) | awaited | | Concurrency | listeners called one after the other | listeners of one event started in order, then awaited together (they run concurrently); events of an array handled one after the other | | Order | runtime listeners (on/once/attach, attachment order), then subscribers in registration order, then methods in declaration order | same start order | | Listener error | reported, other listeners still run | same; the promise never rejects because of a listener | | Async rejection | reported (never an unhandled rejection) | reported | | Result | non-empty results (isEmpty), in call order; pending promises count as empty | non-empty resolved results, in call order | | No listener | no-op, [] | [] | | Throws | only if a subscriber cannot be resolved (message Error instantiating class "X": ..., container error as cause) | rejects in the same case |

• Errors are reported with console.error("[event-dispatching] Listener <Class.method> failed for event \"<event>\":", error). The original error object (message, stack, cause) is logged as is. The payload is never logged: it can hold users, tokens or sessions.
• Payload: every listener receives the same object reference. It is neither cloned nor frozen; do not mutate it unless the event contract says so.
• Nested dispatch: a listener may dispatch other events. With dispatch(), the nested event is fully handled before the outer listener continues.
• Request context: listeners run in the caller's async context, so AsyncLocalStorage (request context, sessions) is preserved, also after await in a listener.
• Listener changes during a dispatch (attach, detach, once) apply from the next dispatch. A once listener is detached before it runs: it runs at most once, even if it throws or several dispatches run concurrently.

Lifecycle and DI

1. Decorators run when a module file is evaluated. They append frozen records to two process-wide lists stored with reflect-metadata on Reflect (DECORATOR_EVENT_SUBSCRIBER_META_KEY, DECORATOR_ON_META_KEY).
2. bootstrap(app) binds MetadataRegistry (singleton) and EventDispatching (container default scope, singleton in the application) and initializes the registry; onPreInit initializes it again to catch modules imported later. Initialization is idempotent.
3. First dispatch: the registry resolves every registered subscriber with container.get(SubscriberClass) (the application container uses autobind), in registration order, then indexes the listeners by event. Instances are cached by the registry for its lifetime: a subscriber behaves as a singleton whatever its binding scope, and is a different object from container.get(TYPES.XSubscriber). A resolution failure is thrown to the dispatching's caller and retried at the next dispatch.
4. Next dispatches read the listeners of the event from the index (no scan, no reflection). Registering new metadata rebuilds the index on the next dispatch.

Listener methods are looked up on the instance at call time, with the instance as this, so injected dependencies (this._manager, this.log, ...) are available.

Typed payloads (optional)

Payloads are any by default. A module can opt in to checked payloads by augmenting EventMap; other events keep working unchanged:

declare module "event-dispatching" {
    interface EventMap {
        "app_auth.user.created": UserCreatedEvent;
    }
}

Testing

• Bind a fake under TYPES.EventDispatching to record dispatches (see app-auth/__test__/helpers.ts).
• To test real subscribers, call the default bootstrap({ container }) with a new Container({ defaultScope: "Singleton", autobind: true }), then get TYPES.EventDispatching.
• The decorator lists are process-wide: save and restore both metadata keys around tests that declare decorated classes (see __tests__/EventDispatching.behavior.test.ts).
• registry.getEventListeners(event) lists the listeners of an event (frozen descriptors with subscriber and method names, no payload).

pnpm --filter event-dispatching exec vitest run
pnpm --filter event-dispatching exec tsc --project tsconfig.json --noEmit
pnpm --filter event-dispatching run build   # consumers read dist