@andygo.dev/emitter 1.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Kramar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,278 @@
+# @andygo.dev/emitter
+
+A thin, **type-safe** NestJS wrapper around
+[`@nestjs/event-emitter`](https://docs.nestjs.com/techniques/events) with an
+**error-catching `@OnEmitterEvent`** decorator.
+
+Three pieces:
+
+- `EmitterService<T>` — typed `emit(...)` / `emitAsync(...)` keyed off your
+  event map.
+- `OnEmitterEvent(...)` — drop-in replacement for `@OnEvent` that catches
+  thrown / rejected errors and logs them via the injected
+  `EMITTER_LOGGER` (NestJS `Logger` by default), so a single bad listener
+  can't take the whole emitter loop down.
+- `EmitterModule.forRoot({...})` — wires the underlying `EventEmitter2` with
+  whatever options you want.
+
+> **Runnable example:** [`examples/complex/`](examples/complex/) — a NestJS
+> app that exercises every feature (typed events, `forRoot` + `forFeature`,
+> async + sync listeners, error catching, cross-module flows). Clone the
+> repo and run `npm run example:complex`.
+
+## Install
+
+```bash
+npm install @andygo.dev/emitter
+```
+
+Peer dependencies:
+
+- `@nestjs/common` `^10 || ^11`
+- `@nestjs/event-emitter` `^2 || ^3`
+
+## Quick start
+
+### 1. Define your event map
+
+A plain TypeScript type — the key is the event name, the value is the payload
+shape. This is the single source of truth for both emit and listen.
+
+```ts
+// app.events.ts
+export interface AppEvents {
+  'user.created': { id: number; email: string };
+  'user.deleted': { id: number };
+  'order.paid': { orderId: number; amount: number };
+}
+```
+
+### 2. Register the module
+
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { EmitterModule } from '@andygo.dev/emitter';
+
+@Module({
+  imports: [
+    EmitterModule.forRoot({
+      // optional — these are the defaults:
+      wildcard: false,
+      delimiter: '.',
+      maxListeners: 50,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Or use the static `EmitterModule` import directly if the defaults are fine —
+it's `@Global()` either way, so you only need it once.
+
+### 3. Emit events
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { EmitterService } from '@andygo.dev/emitter';
+import { AppEvents } from './app.events';
+
+@Injectable()
+export class UsersService {
+  constructor(private readonly events: EmitterService<AppEvents>) {}
+
+  async create(input: CreateUserDto) {
+    const user = await this.repo.save(input);
+
+    // ✓ key + payload are checked against AppEvents
+    await this.events.emitAsync('user.created', { id: user.id, email: user.email });
+
+    return user;
+  }
+}
+```
+
+Both methods are strictly typed: passing the wrong event name or a payload
+that doesn't match `AppEvents[key]` is a compile error.
+
+| Method | Returns | When to use |
+|---|---|---|
+| `emit(name, payload)` | `boolean` (was anyone listening?) | Fire-and-forget |
+| `emitAsync(name, payload)` | `Promise<any[]>` of all listener return values | When you need to wait for handlers to finish |
+
+### 4. Listen for events
+
+Use `@OnEmitterEvent` instead of `@OnEvent`. Same API, but a listener that
+throws or rejects is caught and logged via the configured logger instead of
+crashing the emitter loop.
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { OnEmitterEvent } from '@andygo.dev/emitter';
+import { AppEvents } from './app.events';
+
+@Injectable()
+export class WelcomeEmailListener {
+  @OnEmitterEvent<AppEvents>('user.created')
+  async sendWelcome(payload: AppEvents['user.created']) {
+    await this.mailer.send(payload.email, 'welcome');
+    // any throw / rejection here is caught + logged, not propagated
+  }
+}
+```
+
+### Synchronous listeners
+
+For non-async handlers, pass `promisify: false` so the wrapper uses
+`try/catch` instead of `.catch()`:
+
+```ts
+@OnEmitterEvent<AppEvents>('user.deleted', { promisify: false })
+purgeCache(payload: AppEvents['user.deleted']) {
+  this.cache.delete(`user:${payload.id}`);
+}
+```
+
+## Why not just `@OnEvent`?
+
+Vanilla `@nestjs/event-emitter` propagates exceptions out of listeners and
+the default `EventEmitter2` will emit an `'error'` event when there's no
+listener — easy to miss in production logs. `@OnEmitterEvent` wraps the
+listener method exactly once (idempotent across stacked decorators on the
+same class) and catches both sync throws and promise rejections, routing
+them to the configured logger so they end up in your normal log pipeline.
+
+## Custom logger
+
+By default `@OnEmitterEvent` logs errors via `new Logger('EmitterModule')`
+(Nest's built-in console logger). Swap in anything that implements
+`LoggerService` via `EmitterModule.forRoot`:
+
+```ts
+import { EmitterModule } from '@andygo.dev/emitter';
+import { PinoLogger } from 'nestjs-pino'; // or your own LoggerService
+
+@Module({
+  imports: [
+    EmitterModule.forRoot({
+      logger: new PinoLogger({ pinoHttp: {} }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Per-module overrides with `forFeature`
+
+`EmitterModule.forFeature({ logger })` overrides `EMITTER_LOGGER` for just
+the importing module. Listeners declared inside that module log under the
+local logger; listeners in other modules continue to use the
+`forRoot`-level default.
+
+`forFeature()` called without a `logger` is effectively a no-op for
+logging — the listener inside that module **falls through to whatever
+`forRoot` configured** (or the package default if no `forRoot` was
+called).
+
+```ts
+// app.module.ts
+@Module({
+  imports: [EmitterModule.forRoot()],          // global default
+})
+export class AppModule {}
+
+// users.module.ts
+@Module({
+  imports: [
+    EmitterModule.forFeature({
+      logger: new Logger('UsersModule'),       // local override
+    }),
+  ],
+  providers: [UserCreatedListener],            // its @OnEmitterEvent
+                                               // handlers log under
+                                               // 'UsersModule'
+})
+export class UsersModule {}
+
+// orders.module.ts
+@Module({
+  imports: [
+    EmitterModule.forFeature({
+      logger: new Logger('OrdersModule'),
+    }),
+  ],
+  providers: [OrderPaidListener],
+})
+export class OrdersModule {}
+```
+
+Under the hood `forFeature({ logger })` provides a separate
+`EMITTER_FEATURE_LOGGER` token (also exported), and the decorator injects
+both `EMITTER_LOGGER` (required, global) and `EMITTER_FEATURE_LOGGER`
+(optional, local) — preferring the feature one when present. This
+sidesteps NestJS's "global module exports beat local imports" resolution
+order; without the two-token split, the global `forRoot` logger would
+silently win and the override would be dropped.
+
+## API
+
+### `EmitterService<T>`
+
+```ts
+class EmitterService<T> {
+  emit<K extends string & keyof T>(eventType: K, eventValue: T[K]): boolean;
+  emitAsync<K extends string & keyof T>(eventType: K, eventValue: T[K]): Promise<any[]>;
+}
+```
+
+### `OnEmitterEvent<T>(eventType, options?)`
+
+```ts
+function OnEmitterEvent<T>(
+  eventType: string & keyof T,
+  options?: {
+    async?: boolean;          // default: true
+    promisify?: boolean;      // default: true
+    suppressErrors?: boolean; // default: false (errors caught by wrapper)
+    // plus everything @OnEvent accepts
+  },
+): MethodDecorator;
+```
+
+### `EmitterModule.forRoot(options?)`
+
+```ts
+EmitterModule.forRoot({
+  // forwarded to EventEmitter2
+  wildcard?: boolean;          // default: false
+  delimiter?: string;          // default: '.'
+  maxListeners?: number;       // default: 50
+  verboseMemoryLeak?: boolean;
+  ignoreErrors?: boolean;
+  newListener?: boolean;
+  removeListener?: boolean;
+
+  // package-specific
+  logger?: LoggerService;      // default: new Logger('EmitterModule')
+});
+```
+
+### `EmitterModule.forFeature(options?)`
+
+Feature-scoped logger override. Returns a non-global `DynamicModule`, so
+the override only applies to providers inside the importing module.
+When `logger` is omitted, the module does not rebind `EMITTER_LOGGER` —
+listeners inside it fall through to whatever was configured by
+`forRoot(...)`. EventEmitter2's `wildcard` / `delimiter` / `maxListeners`
+are process-global and cannot be changed per-feature — configure those
+via `forRoot`.
+
+```ts
+EmitterModule.forFeature({
+  logger?: LoggerService;      // omit to inherit from forRoot
+});
+```
+
+## License
+
+MIT

package/dist/constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Injection token for the root-level logger used by `@OnEmitterEvent`.
+ * Provided by `EmitterModule` with a default `new Logger('EmitterModule')`
+ * and overridable via `EmitterModule.forRoot({ logger })`. Always
+ * available — `forRoot` exports it globally.
+ */
+export declare const EMITTER_LOGGER: unique symbol;
+/**
+ * Injection token for an optional per-feature logger override.
+ * Only provided when a caller passes `logger` to
+ * `EmitterModule.forFeature({ logger })`. The `@OnEmitterEvent` decorator
+ * prefers this over `EMITTER_LOGGER` when both are available, which is
+ * how feature modules can route their listener errors to their own
+ * logger without disturbing the global default.
+ */
+export declare const EMITTER_FEATURE_LOGGER: unique symbol;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,cAAc,eAA2B,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,eAAmC,CAAC"}

package/dist/constants.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMITTER_FEATURE_LOGGER = exports.EMITTER_LOGGER = void 0;
+/**
+ * Injection token for the root-level logger used by `@OnEmitterEvent`.
+ * Provided by `EmitterModule` with a default `new Logger('EmitterModule')`
+ * and overridable via `EmitterModule.forRoot({ logger })`. Always
+ * available — `forRoot` exports it globally.
+ */
+exports.EMITTER_LOGGER = Symbol('EMITTER_LOGGER');
+/**
+ * Injection token for an optional per-feature logger override.
+ * Only provided when a caller passes `logger` to
+ * `EmitterModule.forFeature({ logger })`. The `@OnEmitterEvent` decorator
+ * prefers this over `EMITTER_LOGGER` when both are available, which is
+ * how feature modules can route their listener errors to their own
+ * logger without disturbing the global default.
+ */
+exports.EMITTER_FEATURE_LOGGER = Symbol('EMITTER_FEATURE_LOGGER');
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACU,QAAA,cAAc,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAEvD;;;;;;;GAOG;AACU,QAAA,sBAAsB,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC"}

package/dist/decorators/on-emitter-event.decorator.d.ts

@@ -0,0 +1,22 @@
+import { OnEvent } from '@nestjs/event-emitter';
+/**
+ * Decorate a method to listen for an emitter event.
+ *
+ * Behaves like `@OnEvent` from `@nestjs/event-emitter`, but wraps the
+ * handler so any thrown / rejected error is caught and reported to the
+ * configured logger:
+ *
+ * - If the listener's module imported `EmitterModule.forFeature({ logger })`,
+ *   that local logger is used.
+ * - Otherwise, the root logger registered by `EmitterModule.forRoot({ logger })`
+ *   (defaulting to `new Logger('EmitterModule')`) is used.
+ *
+ * Options:
+ *
+ * - `promisify: true` (default) — the handler must return a Promise;
+ *   rejections are caught with `.catch(...)`.
+ * - `promisify: false` — the handler is treated as synchronous; throws
+ *   are caught with try/catch and `undefined` is returned.
+ */
+export declare function OnEmitterEvent<T>(eventType: string & keyof T, options?: Parameters<typeof OnEvent>[1]): (target: any, _property: string, descriptor: PropertyDescriptor) => void | TypedPropertyDescriptor<any>;
+//# sourceMappingURL=on-emitter-event.decorator.d.ts.map

package/dist/decorators/on-emitter-event.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"on-emitter-event.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/on-emitter-event.decorator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAMhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,EAC3B,OAAO,GAAE,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAM,IAEnC,QAAQ,GAAG,EAAE,WAAW,MAAM,EAAE,YAAY,kBAAkB,yCAuCvE"}

package/dist/decorators/on-emitter-event.decorator.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnEmitterEvent = OnEmitterEvent;
+const common_1 = require("@nestjs/common");
+const event_emitter_1 = require("@nestjs/event-emitter");
+const constants_1 = require("../constants");
+const WRAPPER_ADDED = Symbol('WRAPPER_ADDED');
+/**
+ * Decorate a method to listen for an emitter event.
+ *
+ * Behaves like `@OnEvent` from `@nestjs/event-emitter`, but wraps the
+ * handler so any thrown / rejected error is caught and reported to the
+ * configured logger:
+ *
+ * - If the listener's module imported `EmitterModule.forFeature({ logger })`,
+ *   that local logger is used.
+ * - Otherwise, the root logger registered by `EmitterModule.forRoot({ logger })`
+ *   (defaulting to `new Logger('EmitterModule')`) is used.
+ *
+ * Options:
+ *
+ * - `promisify: true` (default) — the handler must return a Promise;
+ *   rejections are caught with `.catch(...)`.
+ * - `promisify: false` — the handler is treated as synchronous; throws
+ *   are caught with try/catch and `undefined` is returned.
+ */
+function OnEmitterEvent(eventType, options = {}) {
+    return (target, _property, descriptor) => {
+        // Required: every listener resolves the global root logger so we always
+        // have a working fallback.
+        (0, common_1.Inject)(constants_1.EMITTER_LOGGER)(target, constants_1.EMITTER_LOGGER);
+        // Optional: the per-feature override is only present when the listener's
+        // module imported `EmitterModule.forFeature({ logger })`.
+        (0, common_1.Inject)(constants_1.EMITTER_FEATURE_LOGGER)(target, constants_1.EMITTER_FEATURE_LOGGER);
+        (0, common_1.Optional)()(target, constants_1.EMITTER_FEATURE_LOGGER);
+        const method = descriptor.value;
+        const onEventOptions = {
+            async: true, promisify: true, suppressErrors: false, ...options,
+        };
+        if (!target[WRAPPER_ADDED]) {
+            descriptor.value = function onEmitterEventWrapper(...args) {
+                const self = this;
+                const logger = self[constants_1.EMITTER_FEATURE_LOGGER]
+                    ?? self[constants_1.EMITTER_LOGGER];
+                if (onEventOptions.promisify === false) {
+                    try {
+                        return method.apply(this, args);
+                    }
+                    catch (error) {
+                        logger.error(error);
+                        return undefined;
+                    }
+                }
+                return method.apply(this, args).catch((error) => {
+                    logger.error(error);
+                });
+            };
+            target[WRAPPER_ADDED] = true;
+        }
+        return (0, event_emitter_1.OnEvent)(eventType, onEventOptions)(target, _property, descriptor);
+    };
+}
+//# sourceMappingURL=on-emitter-event.decorator.js.map

package/dist/decorators/on-emitter-event.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"on-emitter-event.decorator.js","sourceRoot":"","sources":["../../src/decorators/on-emitter-event.decorator.ts"],"names":[],"mappings":";;AA0BA,wCA2CC;AArED,2CAAiE;AACjE,yDAAgD;AAEhD,4CAAsE;AAEtE,MAAM,aAAa,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,cAAc,CAC5B,SAA2B,EAC3B,UAAyC,EAAE;IAE3C,OAAO,CAAC,MAAW,EAAE,SAAiB,EAAE,UAA8B,EAAE,EAAE;QACxE,wEAAwE;QACxE,2BAA2B;QAC3B,IAAA,eAAM,EAAC,0BAAc,CAAC,CAAC,MAAM,EAAE,0BAAc,CAAC,CAAC;QAE/C,yEAAyE;QACzE,0DAA0D;QAC1D,IAAA,eAAM,EAAC,kCAAsB,CAAC,CAAC,MAAM,EAAE,kCAAsB,CAAC,CAAC;QAC/D,IAAA,iBAAQ,GAAE,CAAC,MAAM,EAAE,kCAAsB,CAAC,CAAC;QAE3C,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC;QAChC,MAAM,cAAc,GAAG;YACrB,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,GAAG,OAAO;SAChE,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;YAC3B,UAAU,CAAC,KAAK,GAAG,SAAS,qBAAqB,CAAC,GAAG,IAAW;gBAC9D,MAAM,IAAI,GAAG,IAAW,CAAC;gBACzB,MAAM,MAAM,GAAI,IAAI,CAAC,kCAAsB,CAA+B;uBACpE,IAAI,CAAC,0BAAc,CAAmB,CAAC;gBAE7C,IAAI,cAAc,CAAC,SAAS,KAAK,KAAK,EAAE,CAAC;oBACvC,IAAI,CAAC;wBACH,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;oBAClC,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;wBAEpB,OAAO,SAAS,CAAC;oBACnB,CAAC;gBACH,CAAC;gBACD,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAU,EAAE,EAAE;oBACnD,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBACtB,CAAC,CAAC,CAAC;YACL,CAAC,CAAC;YACF,MAAM,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;QAC/B,CAAC;QAED,OAAO,IAAA,uBAAO,EAAC,SAAS,EAAE,cAAc,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAC3E,CAAC,CAAC;AACJ,CAAC"}

package/dist/emitter.module.d.ts

@@ -0,0 +1,92 @@
+import { DynamicModule, LoggerService } from '@nestjs/common';
+export interface EmitterModuleOptions {
+    wildcard?: boolean;
+    delimiter?: string;
+    maxListeners?: number;
+    verboseMemoryLeak?: boolean;
+    ignoreErrors?: boolean;
+    newListener?: boolean;
+    removeListener?: boolean;
+    global?: boolean;
+    /**
+     * Logger used by `@OnEmitterEvent` when a listener throws or rejects.
+     * Anything implementing NestJS's `LoggerService` interface works —
+     * Nest's built-in `Logger`, `pino`, `winston`, your project's
+     * `LoggerService`, etc.
+     *
+     * Defaults to `new Logger('EmitterModule')` (the NestJS console logger).
+     */
+    logger?: LoggerService;
+}
+/**
+ * Options accepted by `EmitterModule.forFeature(...)` — currently just the
+ * logger. EventEmitter2's `wildcard` / `delimiter` / `maxListeners` are
+ * process-global and can only be configured via `forRoot(...)`.
+ */
+export interface EmitterFeatureOptions {
+    /**
+     * Logger to use for listeners declared inside the importing module.
+     * Falls back to the root-level `EMITTER_LOGGER` (set via `forRoot`,
+     * defaulting to `new Logger('EmitterModule')`) when omitted.
+     */
+    logger?: LoggerService;
+}
+export declare class EmitterModule {
+    /**
+     * Use `EmitterModule.forRoot({...})` to override the default
+     * EventEmitter2 configuration and/or supply a custom logger.
+     *
+     * Default options are: `{ wildcard: false, delimiter: '.', maxListeners: 50 }`.
+     * Default logger is `new Logger('EmitterModule')`.
+     *
+     * The returned module is global — `EmitterService` and `EMITTER_LOGGER`
+     * are available app-wide without explicit imports.
+     */
+    static forRoot(options?: EmitterModuleOptions): DynamicModule;
+    /**
+     * Override the logger used by `@OnEmitterEvent` for listeners declared
+     * inside the importing module.
+     *
+     * Implementation note: `forFeature` provides a separate
+     * `EMITTER_FEATURE_LOGGER` token, *not* a second binding of
+     * `EMITTER_LOGGER`. The decorator injects both tokens and prefers the
+     * feature one when present. This sidesteps NestJS's "global module
+     * exports beat local imports" resolution — without it, `forRoot`'s
+     * global `EMITTER_LOGGER` would always win and the override would be
+     * silently dropped.
+     *
+     * If `options.logger` is omitted, the feature module is effectively
+     * a no-op (still useful as documentation that a module wants
+     * emitter-aware logging), and listeners inside it fall through to
+     * the root-level `EMITTER_LOGGER` from `forRoot(...)`.
+     *
+     * @example
+     * ```ts
+     * // app.module.ts
+     * @Module({
+     *   imports: [EmitterModule.forRoot({ logger: rootLogger })],
+     * })
+     * export class AppModule {}
+     *
+     * // users.module.ts — overrides the root logger locally
+     * @Module({
+     *   imports: [
+     *     EmitterModule.forFeature({
+     *       logger: new Logger('UsersModule'),
+     *     }),
+     *   ],
+     *   providers: [UserCreatedListener],
+     * })
+     * export class UsersModule {}
+     *
+     * // orders.module.ts — no override, falls back to rootLogger
+     * @Module({
+     *   imports: [EmitterModule.forFeature()],
+     *   providers: [OrderPaidListener],
+     * })
+     * export class OrdersModule {}
+     * ```
+     */
+    static forFeature(options?: EmitterFeatureOptions): DynamicModule;
+}
+//# sourceMappingURL=emitter.module.d.ts.map

package/dist/emitter.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.module.d.ts","sourceRoot":"","sources":["../src/emitter.module.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EAAkB,aAAa,EAC7C,MAAM,gBAAgB,CAAC;AAMxB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AA6BD,qBASa,aAAa;IACxB;;;;;;;;;OASG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa;IAgBjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,MAAM,CAAC,UAAU,CAAC,OAAO,GAAE,qBAA0B,GAAG,aAAa;CAmBtE"}

package/dist/emitter.module.js

@@ -0,0 +1,139 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var EmitterModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmitterModule = void 0;
+const common_1 = require("@nestjs/common");
+const event_emitter_1 = require("@nestjs/event-emitter");
+const constants_1 = require("./constants");
+const emitter_service_1 = require("./services/emitter.service");
+const EVENT_EMITTER_KEYS = [
+    'wildcard',
+    'delimiter',
+    'maxListeners',
+    'verboseMemoryLeak',
+    'ignoreErrors',
+    'newListener',
+    'removeListener',
+    'global',
+];
+const DEFAULT_OPTIONS = {
+    wildcard: false,
+    delimiter: '.',
+    maxListeners: 50,
+};
+const DEFAULT_LOGGER = new common_1.Logger('EmitterModule');
+function pickEventEmitterOptions(options) {
+    const out = {};
+    for (const key of EVENT_EMITTER_KEYS) {
+        if (options[key] !== undefined)
+            out[key] = options[key];
+    }
+    return out;
+}
+let EmitterModule = EmitterModule_1 = class EmitterModule {
+    /**
+     * Use `EmitterModule.forRoot({...})` to override the default
+     * EventEmitter2 configuration and/or supply a custom logger.
+     *
+     * Default options are: `{ wildcard: false, delimiter: '.', maxListeners: 50 }`.
+     * Default logger is `new Logger('EmitterModule')`.
+     *
+     * The returned module is global — `EmitterService` and `EMITTER_LOGGER`
+     * are available app-wide without explicit imports.
+     */
+    static forRoot(options = {}) {
+        const merged = { ...DEFAULT_OPTIONS, ...options };
+        const logger = options.logger ?? DEFAULT_LOGGER;
+        return {
+            module: EmitterModule_1,
+            global: true,
+            imports: [event_emitter_1.EventEmitterModule.forRoot(pickEventEmitterOptions(merged))],
+            providers: [
+                emitter_service_1.EmitterService,
+                { provide: constants_1.EMITTER_LOGGER, useValue: logger },
+            ],
+            exports: [emitter_service_1.EmitterService, constants_1.EMITTER_LOGGER],
+        };
+    }
+    /**
+     * Override the logger used by `@OnEmitterEvent` for listeners declared
+     * inside the importing module.
+     *
+     * Implementation note: `forFeature` provides a separate
+     * `EMITTER_FEATURE_LOGGER` token, *not* a second binding of
+     * `EMITTER_LOGGER`. The decorator injects both tokens and prefers the
+     * feature one when present. This sidesteps NestJS's "global module
+     * exports beat local imports" resolution — without it, `forRoot`'s
+     * global `EMITTER_LOGGER` would always win and the override would be
+     * silently dropped.
+     *
+     * If `options.logger` is omitted, the feature module is effectively
+     * a no-op (still useful as documentation that a module wants
+     * emitter-aware logging), and listeners inside it fall through to
+     * the root-level `EMITTER_LOGGER` from `forRoot(...)`.
+     *
+     * @example
+     * ```ts
+     * // app.module.ts
+     * @Module({
+     *   imports: [EmitterModule.forRoot({ logger: rootLogger })],
+     * })
+     * export class AppModule {}
+     *
+     * // users.module.ts — overrides the root logger locally
+     * @Module({
+     *   imports: [
+     *     EmitterModule.forFeature({
+     *       logger: new Logger('UsersModule'),
+     *     }),
+     *   ],
+     *   providers: [UserCreatedListener],
+     * })
+     * export class UsersModule {}
+     *
+     * // orders.module.ts — no override, falls back to rootLogger
+     * @Module({
+     *   imports: [EmitterModule.forFeature()],
+     *   providers: [OrderPaidListener],
+     * })
+     * export class OrdersModule {}
+     * ```
+     */
+    static forFeature(options = {}) {
+        // Fresh class per call so Nest doesn't dedupe the feature import.
+        class EmitterFeatureModule {
+        }
+        if (options.logger === undefined) {
+            // No override — listeners fall through to root EMITTER_LOGGER.
+            return {
+                module: EmitterFeatureModule,
+            };
+        }
+        return {
+            module: EmitterFeatureModule,
+            providers: [
+                { provide: constants_1.EMITTER_FEATURE_LOGGER, useValue: options.logger },
+            ],
+            exports: [constants_1.EMITTER_FEATURE_LOGGER],
+        };
+    }
+};
+exports.EmitterModule = EmitterModule;
+exports.EmitterModule = EmitterModule = EmitterModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({
+        imports: [event_emitter_1.EventEmitterModule.forRoot(pickEventEmitterOptions(DEFAULT_OPTIONS))],
+        providers: [
+            emitter_service_1.EmitterService,
+            { provide: constants_1.EMITTER_LOGGER, useValue: DEFAULT_LOGGER },
+        ],
+        exports: [emitter_service_1.EmitterService, constants_1.EMITTER_LOGGER],
+    })
+], EmitterModule);
+//# sourceMappingURL=emitter.module.js.map

package/dist/emitter.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.module.js","sourceRoot":"","sources":["../src/emitter.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAEwB;AACxB,yDAA2D;AAE3D,2CAAqE;AACrE,gEAA4D;AAqC5D,MAAM,kBAAkB,GAAG;IACzB,UAAU;IACV,WAAW;IACX,cAAc;IACd,mBAAmB;IACnB,cAAc;IACd,aAAa;IACb,gBAAgB;IAChB,QAAQ;CACA,CAAC;AAEX,MAAM,eAAe,GAAyB;IAC5C,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,GAAG;IACd,YAAY,EAAE,EAAE;CACjB,CAAC;AAEF,MAAM,cAAc,GAAkB,IAAI,eAAM,CAAC,eAAe,CAAC,CAAC;AAElE,SAAS,uBAAuB,CAAC,OAA6B;IAC5D,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAWM,IAAM,aAAa,qBAAnB,MAAM,aAAa;IACxB;;;;;;;;;OASG;IACH,MAAM,CAAC,OAAO,CAAC,UAAgC,EAAE;QAC/C,MAAM,MAAM,GAAG,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC;QAEhD,OAAO;YACL,MAAM,EAAE,eAAa;YACrB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,CAAC,kCAAkB,CAAC,OAAO,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAAC;YACtE,SAAS,EAAE;gBACT,gCAAc;gBACd,EAAE,OAAO,EAAE,0BAAc,EAAE,QAAQ,EAAE,MAAM,EAAE;aAC9C;YACD,OAAO,EAAE,CAAC,gCAAc,EAAE,0BAAc,CAAC;SAC1C,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,MAAM,CAAC,UAAU,CAAC,UAAiC,EAAE;QACnD,kEAAkE;QAClE,MAAM,oBAAoB;SAAG;QAE7B,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACjC,+DAA+D;YAC/D,OAAO;gBACL,MAAM,EAAE,oBAAoB;aAC7B,CAAC;QACJ,CAAC;QAED,OAAO;YACL,MAAM,EAAE,oBAAoB;YAC5B,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,kCAAsB,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,EAAE;aAC9D;YACD,OAAO,EAAE,CAAC,kCAAsB,CAAC;SAClC,CAAC;IACJ,CAAC;CACF,CAAA;AA1FY,sCAAa;wBAAb,aAAa;IATzB,IAAA,eAAM,GAAE;IACR,IAAA,eAAM,EAAC;QACN,OAAO,EAAE,CAAC,kCAAkB,CAAC,OAAO,CAAC,uBAAuB,CAAC,eAAe,CAAC,CAAC,CAAC;QAC/E,SAAS,EAAE;YACT,gCAAc;YACd,EAAE,OAAO,EAAE,0BAAc,EAAE,QAAQ,EAAE,cAAc,EAAE;SACtD;QACD,OAAO,EAAE,CAAC,gCAAc,EAAE,0BAAc,CAAC;KAC1C,CAAC;GACW,aAAa,CA0FzB"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { EmitterService } from './services/emitter.service';
+export { EmitterModule, EmitterModuleOptions, EmitterFeatureOptions } from './emitter.module';
+export { OnEmitterEvent } from './decorators/on-emitter-event.decorator';
+export { EMITTER_LOGGER, EMITTER_FEATURE_LOGGER } from './constants';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMITTER_FEATURE_LOGGER = exports.EMITTER_LOGGER = exports.OnEmitterEvent = exports.EmitterModule = exports.EmitterService = void 0;
+var emitter_service_1 = require("./services/emitter.service");
+Object.defineProperty(exports, "EmitterService", { enumerable: true, get: function () { return emitter_service_1.EmitterService; } });
+var emitter_module_1 = require("./emitter.module");
+Object.defineProperty(exports, "EmitterModule", { enumerable: true, get: function () { return emitter_module_1.EmitterModule; } });
+var on_emitter_event_decorator_1 = require("./decorators/on-emitter-event.decorator");
+Object.defineProperty(exports, "OnEmitterEvent", { enumerable: true, get: function () { return on_emitter_event_decorator_1.OnEmitterEvent; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "EMITTER_LOGGER", { enumerable: true, get: function () { return constants_1.EMITTER_LOGGER; } });
+Object.defineProperty(exports, "EMITTER_FEATURE_LOGGER", { enumerable: true, get: function () { return constants_1.EMITTER_FEATURE_LOGGER; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,8DAA4D;AAAnD,iHAAA,cAAc,OAAA;AACvB,mDAA8F;AAArF,+GAAA,aAAa,OAAA;AACtB,sFAAyE;AAAhE,4HAAA,cAAc,OAAA;AACvB,yCAAqE;AAA5D,2GAAA,cAAc,OAAA;AAAE,mHAAA,sBAAsB,OAAA"}

package/dist/services/emitter.service.d.ts

@@ -0,0 +1,7 @@
+import { EventEmitter2 } from '@nestjs/event-emitter';
+export declare class EmitterService<T> {
+    protected emitter2: EventEmitter2;
+    emitAsync<key extends string & keyof T>(eventType: key, eventValue: T[key]): Promise<any[]>;
+    emit<key extends string & keyof T>(eventType: key, eventValue: T[key]): boolean;
+}
+//# sourceMappingURL=emitter.service.d.ts.map

package/dist/services/emitter.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.service.d.ts","sourceRoot":"","sources":["../../src/services/emitter.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,qBACa,cAAc,CAAC,CAAC;IAE3B,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC;IAElC,SAAS,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC;IAI1E,IAAI,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC;CAGtE"}

package/dist/services/emitter.service.js

@@ -0,0 +1,32 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmitterService = void 0;
+const common_1 = require("@nestjs/common");
+const event_emitter_1 = require("@nestjs/event-emitter");
+let EmitterService = class EmitterService {
+    emitter2;
+    emitAsync(eventType, eventValue) {
+        return this.emitter2.emitAsync(eventType, eventValue, eventType);
+    }
+    emit(eventType, eventValue) {
+        return this.emitter2.emit(eventType, eventValue, eventType);
+    }
+};
+exports.EmitterService = EmitterService;
+__decorate([
+    (0, common_1.Inject)(),
+    __metadata("design:type", event_emitter_1.EventEmitter2)
+], EmitterService.prototype, "emitter2", void 0);
+exports.EmitterService = EmitterService = __decorate([
+    (0, common_1.Injectable)()
+], EmitterService);
+//# sourceMappingURL=emitter.service.js.map

package/dist/services/emitter.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.service.js","sourceRoot":"","sources":["../../src/services/emitter.service.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAoD;AACpD,yDAAsD;AAG/C,IAAM,cAAc,GAApB,MAAM,cAAc;IAEf,QAAQ,CAAgB;IAElC,SAAS,CAA+B,SAAc,EAAE,UAAkB;QACxE,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IACnE,CAAC;IAED,IAAI,CAA+B,SAAc,EAAE,UAAkB;QACnE,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAC9D,CAAC;CACF,CAAA;AAXY,wCAAc;AAEf;IADT,IAAA,eAAM,GAAE;8BACW,6BAAa;gDAAC;yBAFvB,cAAc;IAD1B,IAAA,mBAAU,GAAE;GACA,cAAc,CAW1B"}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@andygo.dev/emitter",
+  "version": "1.3.4",
+  "description": "Type-safe wrapper around @nestjs/event-emitter with an error-catching @OnEmitterEvent decorator.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "lint": "eslint \"{src,tests}/**/*.ts\" --max-warnings=0",
+    "lint:fix": "eslint \"{src,tests}/**/*.ts\" --max-warnings=0 --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "example:complex": "ts-node --project tsconfig.examples.json examples/main.ts",
+    "prepublishOnly": "npm run clean && npm run build",
+    "preversion": "npm run lint && npm test && npm run build",
+    "postversion": "git push --follow-tags && npm publish --access public",
+    "publish": "npm publish --access public",
+    "bump:patch": "npm version patch --no-git-tag-version",
+    "bump:minor": "npm version minor --no-git-tag-version",
+    "bump:major": "npm version major --no-git-tag-version"
+  },
+  "keywords": [
+    "nestjs",
+    "event-emitter",
+    "events",
+    "typescript",
+    "decorator"
+  ],
+  "author": "Andy Kramar <andygo.develop@gmail.com>",
+  "license": "MIT",
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/event-emitter": "^2.0.0 || ^3.0.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.3",
+    "@nestjs/core": "^11.1.3",
+    "@nestjs/event-emitter": "^3.0.1",
+    "@nestjs/testing": "^11.1.3",
+    "@types/jest": "29.5.14",
+    "@types/node": "^20.0.0",
+    "eslint": "^9.0.0",
+    "jest": "29.7.0",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.8.0",
+    "ts-jest": "29.2.5",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0",
+    "typescript-eslint": "^8.0.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "rootDir": ".",
+    "testMatch": [
+      "<rootDir>/tests/**/*.spec.ts"
+    ],
+    "moduleFileExtensions": [
+      "ts",
+      "js",
+      "json"
+    ],
+    "transform": {
+      "^.+\\.ts$": [
+        "ts-jest",
+        {
+          "tsconfig": "tsconfig.test.json",
+          "diagnostics": true
+        }
+      ]
+    },
+    "collectCoverageFrom": [
+      "src/**/*.ts",
+      "!src/index.ts"
+    ]
+  }
+}