@adonisjs/events 10.1.0-next.0 → 10.1.0-next.2

package/README.md

@@ -21,8 +21,8 @@ In order to ensure that the AdonisJS community is welcoming to all, please revie
 ## License
 AdonisJS events is open-sourced software licensed under the [MIT license](LICENSE.md).
 
-[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/events/test.yml?style=for-the-badge
-[gh-workflow-url]: https://github.com/adonisjs/events/actions/workflows/test.yml "Github action"
+[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/events/checks.yml?style=for-the-badge
+[gh-workflow-url]: https://github.com/adonisjs/events/actions/workflows/checks.yml "Github action"
 
 [typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
 [typescript-url]:  "typescript"

package/build/{chunk-26H7HMEN.js → chunk-R74HJGSQ.js}

@@ -1,3 +1,17 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/tracing_channels.ts
+var tracing_channels_exports = {};
+__export(tracing_channels_exports, {
+  eventDispatch: () => eventDispatch
+});
+import diagnostics_channel from "diagnostics_channel";
+var eventDispatch = diagnostics_channel.tracingChannel("adonisjs.event.dispatch");
+
 // src/emitter.ts
 import is2 from "@sindresorhus/is";
 import Emittery from "emittery";
@@ -18,30 +32,45 @@ var EventsBuffer = class {
   #events = [];
   /**
    * Track emitted event
+   *
+   * @param event - The event that was emitted
+   * @param data - The data passed with the event
    */
   add(event, data) {
     this.#events.push({ event, data });
   }
   /**
    * Get all the emitted events
+   *
+   * @returns Array of all buffered events
    */
   all() {
     return this.#events;
   }
   /**
    * Returns the size of captured events
+   *
+   * @returns The number of captured events
    */
   size() {
     return this.#events.length;
   }
   /**
    * Find if an event was emitted
+   *
+   * @param event - The event to check for
+   * @param finder - Optional callback to filter specific event instances
+   * @returns True if the event was emitted
    */
   exists(event, finder) {
     return !!this.find(event, finder);
   }
   /**
    * Find a specific event
+   *
+   * @param event - The event to find
+   * @param finder - Optional callback to filter specific event instances
+   * @returns The found event or null
    */
   find(event, finder) {
     return this.#events.find((bufferedEvent) => {
@@ -53,6 +82,10 @@ var EventsBuffer = class {
   }
   /**
    * Assert a given event has been emitted
+   *
+   * @param event - The event to assert was emitted
+   * @param finder - Optional callback to filter specific event instances
+   * @throws AssertionError if the event was not emitted
    */
   assertEmitted(event, finder) {
     const hasEvent = this.exists(event, finder);
@@ -69,6 +102,10 @@ var EventsBuffer = class {
   }
   /**
    * Assert number of times an event has been emitted
+   *
+   * @param event - The event to check emission count for
+   * @param count - The expected number of emissions
+   * @throws AssertionError if the count doesn't match
    */
   assertEmittedCount(event, count) {
     const actual = this.all().filter((bufferedEvent) => bufferedEvent.event === event).length;
@@ -86,6 +123,10 @@ var EventsBuffer = class {
   }
   /**
    * Assert a given event has been not been emitted
+   *
+   * @param event - The event to assert was not emitted
+   * @param finder - Optional callback to filter specific event instances
+   * @throws AssertionError if the event was emitted
    */
   assertNotEmitted(event, finder) {
     const hasEvent = this.exists(event, finder);
@@ -102,7 +143,9 @@ var EventsBuffer = class {
     }
   }
   /**
-   * Assert a given event has been not been emitted
+   * Assert no events have been emitted
+   *
+   * @throws AssertionError if any events were emitted
    */
   assertNoneEmitted() {
     const eventsSize = this.size();
@@ -175,21 +218,34 @@ var Emitter = class {
    *
    * The listeners map key is the original binding listener
    * and the value is a callback function.
+   *
+   * @returns The events listeners map
    */
   get eventsListeners() {
     return this.#eventsListeners;
   }
+  /**
+   * Creates a new Emitter instance
+   *
+   * @param app - The AdonisJS application instance
+   */
   constructor(app) {
     this.#app = app;
   }
   /**
    * Check if the value is a constructor and narrow down its types
+   *
+   * @param value - The value to check
+   * @returns True if the value is a constructor
    */
   #isConstructor(value) {
     return is2.class(value);
   }
   /**
    * Returns the symbol for a class based event.
+   *
+   * @param event - The event class constructor
+   * @returns The symbol for the event class
    */
   #getEventClassSymbol(event) {
     if (!this.#eventsClassSymbols.has(event)) {
@@ -200,6 +256,9 @@ var Emitter = class {
   /**
    * Normalizes the event to emittery supported data types. The class
    * constructors are cached against a unique symbol.
+   *
+   * @param event - The event to resolve
+   * @returns The resolved event as string, symbol, or number
    */
   #resolveEvent(event) {
     if (this.#isConstructor(event)) {
@@ -209,6 +268,9 @@ var Emitter = class {
   }
   /**
    * Returns the event listeners map
+   *
+   * @param event - The event to get listeners for
+   * @returns The listeners map for the event
    */
   #getEventListeners(event) {
     if (!this.#eventsListeners.has(event)) {
@@ -219,6 +281,9 @@ var Emitter = class {
   /**
    * Normalizes the event listener to a function that can be passed to
    * emittery.
+   *
+   * @param listener - The listener to normalize
+   * @returns The normalized listener method
    */
   #normalizeEventListener(listener) {
     if (typeof listener === "string") {
@@ -242,6 +307,10 @@ var Emitter = class {
   /**
    * Resolves the event listener either from the cache or normalizes
    * it and stores it inside the cache
+   *
+   * @param event - The event to resolve listener for
+   * @param listener - The listener to resolve
+   * @returns The resolved listener method
    */
   #resolveEventListener(event, listener) {
     const eventListeners = this.#getEventListeners(event);
@@ -252,6 +321,9 @@ var Emitter = class {
   }
   /**
    * Register a global error handler
+   *
+   * @param callback - The error handler callback
+   * @returns The emitter instance for method chaining
    */
   onError(callback) {
     this.#errorHandler = callback;
@@ -261,6 +333,9 @@ var Emitter = class {
    * Bind multiple listeners to listen for a single event. The listen
    * method is a convenience helper to be used with class based
    * events and listeners.
+   *
+   * @param event - The event class to listen for
+   * @param listeners - Array of listener classes with handle methods
    */
   listen(event, listeners) {
     listeners.forEach((listener) => this.on(event, [listener, "handle"]));
@@ -296,6 +371,9 @@ var Emitter = class {
   /**
    * Attach a listener to listen for all the events. Wildcard listeners
    * can only be defined as inline callbacks.
+   *
+   * @param listener - The wildcard listener callback
+   * @returns The unsubscribe function
    */
   onAny(listener) {
     return this.#transport.onAny(listener);
@@ -308,7 +386,16 @@ var Emitter = class {
     }
     try {
       const normalizedEvent = this.#resolveEvent(event);
-      await this.#transport.emit(normalizedEvent, data);
+      await eventDispatch.tracePromise(
+        this.#transport.emit,
+        eventDispatch.hasSubscribers ? {
+          event,
+          data
+        } : void 0,
+        this.#transport,
+        normalizedEvent,
+        data
+      );
     } catch (error) {
       if (this.#errorHandler) {
         this.#errorHandler(event, error, data);
@@ -325,7 +412,16 @@ var Emitter = class {
     }
     try {
       const normalizedEvent = this.#resolveEvent(event);
-      await this.#transport.emitSerial(normalizedEvent, data);
+      await eventDispatch.tracePromise(
+        this.#transport.emitSerial,
+        eventDispatch.hasSubscribers ? {
+          event,
+          data
+        } : void 0,
+        this.#transport,
+        normalizedEvent,
+        data
+      );
     } catch (error) {
       if (this.#errorHandler) {
         this.#errorHandler(event, error, data);
@@ -336,6 +432,9 @@ var Emitter = class {
   }
   /**
    * Remove a specific listener for an event
+   *
+   * @param event - The event to remove listener from
+   * @param listener - The listener to remove
    */
   off(event, listener) {
     if (debug_default.enabled) {
@@ -352,6 +451,9 @@ var Emitter = class {
   }
   /**
    * Remove a specific listener listening for all the events
+   *
+   * @param listener - The wildcard listener to remove
+   * @returns The emitter instance for method chaining
    */
   offAny(listener) {
     this.#transport.offAny(listener);
@@ -361,12 +463,16 @@ var Emitter = class {
    * Remove a specific listener for an event
    *
    * @alias "off"
+   * @param event - The event to remove listener from
+   * @param listener - The listener to remove
    */
   clearListener(event, listener) {
     return this.off(event, listener);
   }
   /**
    * Clear all listeners for a specific event
+   *
+   * @param event - The event to clear listeners for
    */
   clearListeners(event) {
     debug_default("clearing all listeners for event %O", event);
@@ -383,12 +489,18 @@ var Emitter = class {
   }
   /**
    * Get count of listeners for a given event or all the events
+   *
+   * @param event - The event to count listeners for (optional)
+   * @returns The number of listeners
    */
   listenerCount(event) {
     return this.#transport.listenerCount(event ? this.#resolveEvent(event) : void 0);
   }
   /**
    * Find if an event has one or more listeners
+   *
+   * @param event - The event to check listeners for (optional)
+   * @returns True if the event has listeners
    */
   hasListeners(event) {
     return this.listenerCount(event) > 0;
@@ -402,6 +514,9 @@ var Emitter = class {
    *
    * Calling this method one than once drops the existing fakes and
    * creates new one.
+   *
+   * @param events - Array of events to fake (optional, defaults to all events)
+   * @returns The events buffer for assertions
    */
   fake(events) {
     this.restore();
@@ -427,5 +542,6 @@ var Emitter = class {
 };
 
 export {
+  tracing_channels_exports,
   Emitter
 };

package/build/factories/emitter.d.ts

@@ -1,5 +1,5 @@
 import type { Application } from '@adonisjs/application';
-import { Emitter } from '../src/emitter.js';
+import { Emitter } from '../src/emitter.ts';
 /**
  * Emitter factory is used to create an instance of emitter
  * for testing

package/build/factories/main.d.ts

@@ -1 +1 @@
-export { EmitterFactory } from './emitter.js';
+export { EmitterFactory } from './emitter.ts';

package/build/factories/main.js

@@ -1,6 +1,6 @@
 import {
   Emitter
-} from "../chunk-26H7HMEN.js";
+} from "../chunk-R74HJGSQ.js";
 
 // factories/emitter.ts
 var EmitterFactory = class {

package/build/index.d.ts

@@ -1,2 +1,3 @@
-export { Emitter } from './src/emitter.js';
-export { BaseEvent } from './src/base_event.js';
+export { Emitter } from './src/emitter.ts';
+export { BaseEvent } from './src/base_event.ts';
+export * as tracingChannels from './src/tracing_channels.ts';

package/build/index.js

@@ -1,10 +1,16 @@
 import {
-  Emitter
-} from "./chunk-26H7HMEN.js";
+  Emitter,
+  tracing_channels_exports
+} from "./chunk-R74HJGSQ.js";
 
 // src/base_event.ts
 import { RuntimeException } from "@poppinss/utils/exception";
 var BaseEvent = class {
+  /**
+   * Base event constructor
+   *
+   * @param _ - Any constructor arguments (unused)
+   */
   constructor(..._) {
   }
   /**
@@ -13,6 +19,8 @@ var BaseEvent = class {
   static emitter;
   /**
    * Specify the emitter instance to use for dispatching events
+   *
+   * @param emitter - The emitter instance to use
    */
   static useEmitter(emitter) {
     this.emitter = emitter;
@@ -20,6 +28,9 @@ var BaseEvent = class {
   /**
    * Dispatch the current class as an event. The method takes the arguments
    * accepted by the class constructor.
+   *
+   * @param args - Constructor arguments for the event instance
+   * @throws RuntimeException if no emitter is configured
    */
   static async dispatch(...args) {
     if (!this.emitter) {
@@ -32,5 +43,6 @@ var BaseEvent = class {
 };
 export {
   BaseEvent,
-  Emitter
+  Emitter,
+  tracing_channels_exports as tracingChannels
 };

package/build/src/base_event.d.ts

@@ -1,9 +1,14 @@
-import type { Emitter } from './emitter.js';
+import type { Emitter } from './emitter.ts';
 /**
  * Base event adds ability to a class to act as an event. You can emit the
  * event by calling "Event.dispatch" method.
  */
 export declare class BaseEvent {
+    /**
+     * Base event constructor
+     *
+     * @param _ - Any constructor arguments (unused)
+     */
     constructor(..._: any[]);
     /**
      * The emitter to use for dispatching events
@@ -11,11 +16,16 @@ export declare class BaseEvent {
     static emitter?: Emitter<any>;
     /**
      * Specify the emitter instance to use for dispatching events
+     *
+     * @param emitter - The emitter instance to use
      */
     static useEmitter(emitter: Emitter<any>): void;
     /**
      * Dispatch the current class as an event. The method takes the arguments
      * accepted by the class constructor.
+     *
+     * @param args - Constructor arguments for the event instance
+     * @throws RuntimeException if no emitter is configured
      */
     static dispatch<T extends typeof BaseEvent>(this: T, ...args: ConstructorParameters<T>): Promise<void>;
 }

package/build/src/emitter.d.ts

@@ -1,8 +1,8 @@
 import type { Application } from '@adonisjs/application';
 import { type UnsubscribeFunction } from 'emittery';
 import { type LazyImport, type Constructor } from '@poppinss/utils/types';
-import { EventsBuffer } from './events_buffer.js';
-import type { Listener, EmitterLike, ListenerMethod, AllowedEventTypes, ListenerClassWithHandleMethod } from './types.js';
+import { EventsBuffer } from './events_buffer.ts';
+import type { Listener, EmitterLike, ListenerMethod, AllowedEventTypes, ListenerClassWithHandleMethod } from './types.ts';
 /**
  * Event emitter is built on top of emittery with support class based
  * events and listeners
@@ -16,37 +16,65 @@ export declare class Emitter<EventsList extends Record<string | symbol | number,
      *
      * The listeners map key is the original binding listener
      * and the value is a callback function.
+     *
+     * @returns The events listeners map
      */
     get eventsListeners(): Map<AllowedEventTypes, Map<Listener<any, Constructor<any>>, ListenerMethod<any>>>;
+    /**
+     * Creates a new Emitter instance
+     *
+     * @param app - The AdonisJS application instance
+     */
     constructor(app: Application<any>);
     /**
      * Register a global error handler
+     *
+     * @param callback - The error handler callback
+     * @returns The emitter instance for method chaining
      */
     onError(callback: (event: keyof EventsList | Constructor<any>, error: any, data: any) => void): this;
     /**
      * Bind multiple listeners to listen for a single event. The listen
      * method is a convenience helper to be used with class based
      * events and listeners.
+     *
+     * @param event - The event class to listen for
+     * @param listeners - Array of listener classes with handle methods
      */
     listen<Event extends Constructor<any>>(event: Event, listeners: (ListenerClassWithHandleMethod<InstanceType<Event>> | LazyImport<ListenerClassWithHandleMethod<InstanceType<Event>>>)[]): void;
     /**
      * Listen for an event. The method returns the unsubscribe function.
+     *
+     * @param event - The event to listen for
+     * @param listener - The listener to register
+     * @returns The unsubscribe function
      */
     on<Event extends Constructor<any>, ListenerClass extends Constructor<any>>(event: Event, listener: Listener<InstanceType<Event>, ListenerClass>): UnsubscribeFunction;
     on<Name extends keyof EventsList, ListenerClass extends Constructor<any>>(event: Name, listener: Listener<EventsList[Name], ListenerClass>): UnsubscribeFunction;
     /**
      * Listen for an event depending on a condition
+     *
+     * @param condition - The condition to check before listening
+     * @param event - The event to listen for
+     * @param listener - The listener to register
+     * @returns The unsubscribe function
      */
     listenIf<Event extends Constructor<any>, ListenerClass extends Constructor<any>>(condition: boolean | (() => boolean), event: Event, listener: Listener<InstanceType<Event>, ListenerClass>): UnsubscribeFunction;
     listenIf<Name extends keyof EventsList, ListenerClass extends Constructor<any>>(condition: boolean | (() => boolean), event: Name, listener: Listener<EventsList[Name], ListenerClass>): UnsubscribeFunction;
     /**
      * Listen for an event only once
+     *
+     * @param event - The event to listen for
+     * @param listener - The listener to register
      */
     once<Event extends Constructor<any>, ListenerClass extends Constructor<any>>(event: Event, listener: Listener<InstanceType<Event>, ListenerClass>): void;
     once<Name extends keyof EventsList, ListenerClass extends Constructor<any>>(event: Name, listener: Listener<EventsList[Name], ListenerClass>): void;
     /**
      * Attach a listener to listen for all the events. Wildcard listeners
      * can only be defined as inline callbacks.
+     *
+     * @param listener - The wildcard listener callback
+     * @returns The unsubscribe function
      */
     onAny(listener: (event: AllowedEventTypes, data: any) => any | Promise<any>): UnsubscribeFunction;
     /**
@@ -54,6 +82,9 @@ export declare class Emitter<EventsList extends Record<string | symbol | number,
      * in parallel.
      *
      * You can await this method to wait for events listeners to finish
+     *
+     * @param event - The event to emit
+     * @param data - The data to pass to listeners
      */
     emit<Event extends Constructor<any>>(event: Event, data: InstanceType<Event>): Promise<void>;
     emit<Name extends keyof EventsList>(event: Name, data: EventsList[Name]): Promise<void>;
@@ -62,25 +93,38 @@ export declare class Emitter<EventsList extends Record<string | symbol | number,
      * in the same sequence as they are registered.
      *
      * You can await this method to wait for events listeners to finish
+     *
+     * @param event - The event to emit
+     * @param data - The data to pass to listeners
      */
     emitSerial<Event extends Constructor<any>>(event: Event, data: InstanceType<Event>): Promise<void>;
     emitSerial<Name extends keyof EventsList>(event: Name, data: EventsList[Name]): Promise<void>;
     /**
      * Remove a specific listener for an event
+     *
+     * @param event - The event to remove listener from
+     * @param listener - The listener to remove
      */
     off(event: keyof EventsList | Constructor<any>, listener: Listener<any, Constructor<any>>): void;
     /**
      * Remove a specific listener listening for all the events
+     *
+     * @param listener - The wildcard listener to remove
+     * @returns The emitter instance for method chaining
      */
     offAny(listener: (event: keyof EventsList | Constructor<any>, data: any) => any | Promise<any>): this;
     /**
      * Remove a specific listener for an event
      *
      * @alias "off"
+     * @param event - The event to remove listener from
+     * @param listener - The listener to remove
      */
     clearListener(event: keyof EventsList | Constructor<any>, listener: Listener<any, Constructor<any>>): void;
     /**
      * Clear all listeners for a specific event
+     *
+     * @param event - The event to clear listeners for
      */
     clearListeners(event: keyof EventsList | Constructor<any>): void;
     /**
@@ -89,10 +133,16 @@ export declare class Emitter<EventsList extends Record<string | symbol | number,
     clearAllListeners(): void;
     /**
      * Get count of listeners for a given event or all the events
+     *
+     * @param event - The event to count listeners for (optional)
+     * @returns The number of listeners
      */
     listenerCount(event?: keyof EventsList | Constructor<any>): number;
     /**
      * Find if an event has one or more listeners
+     *
+     * @param event - The event to check listeners for (optional)
+     * @returns True if the event has listeners
      */
     hasListeners(event?: keyof EventsList | Constructor<any>): boolean;
     /**
@@ -104,6 +154,9 @@ export declare class Emitter<EventsList extends Record<string | symbol | number,
      *
      * Calling this method one than once drops the existing fakes and
      * creates new one.
+     *
+     * @param events - Array of events to fake (optional, defaults to all events)
+     * @returns The events buffer for assertions
      */
     fake(events?: (keyof EventsList | Constructor<any>)[]): EventsBuffer<EventsList>;
     /**

package/build/src/events_buffer.d.ts

@@ -1,5 +1,5 @@
 import { type Constructor } from '@poppinss/utils/types';
-import type { AllowedEventTypes, BufferedEvent, BufferedEventsList } from './types.js';
+import type { AllowedEventTypes, BufferedEvent, BufferedEventsList } from './types.ts';
 /**
  * Callback function to narrow down an event from
  * the events buffer list
@@ -12,38 +12,67 @@ export declare class EventsBuffer<EventsList extends Record<string | symbol | nu
     #private;
     /**
      * Track emitted event
+     *
+     * @param event - The event that was emitted
+     * @param data - The data passed with the event
      */
     add<Name extends AllowedEventTypes>(event: Name, data: any): void;
     /**
      * Get all the emitted events
+     *
+     * @returns Array of all buffered events
      */
     all(): BufferedEventsList<EventsList>[];
     /**
      * Returns the size of captured events
+     *
+     * @returns The number of captured events
      */
     size(): number;
     /**
      * Find if an event was emitted
+     *
+     * @param event - The event to check for
+     * @param finder - Optional callback to filter specific event instances
+     * @returns True if the event was emitted
      */
     exists<Event extends keyof EventsList | Constructor<any>>(event: Event, finder?: EventFinderCallback<EventsList, Event>): boolean;
     /**
      * Find a specific event
+     *
+     * @param event - The event to find
+     * @param finder - Optional callback to filter specific event instances
+     * @returns The found event or null
      */
     find<Event extends keyof EventsList | Constructor<any>>(event: Event, finder?: EventFinderCallback<EventsList, Event>): (Event extends keyof EventsList ? BufferedEvent<Event, EventsList[Event]> : Event extends Constructor<infer A> ? BufferedEvent<Event, A> : never) | null;
     /**
      * Assert a given event has been emitted
+     *
+     * @param event - The event to assert was emitted
+     * @param finder - Optional callback to filter specific event instances
+     * @throws AssertionError if the event was not emitted
      */
     assertEmitted<Event extends keyof EventsList | Constructor<any>>(event: Event, finder?: EventFinderCallback<EventsList, Event>): void;
     /**
      * Assert number of times an event has been emitted
+     *
+     * @param event - The event to check emission count for
+     * @param count - The expected number of emissions
+     * @throws AssertionError if the count doesn't match
      */
     assertEmittedCount<Event extends keyof EventsList | Constructor<any>>(event: Event, count: number): void;
     /**
      * Assert a given event has been not been emitted
+     *
+     * @param event - The event to assert was not emitted
+     * @param finder - Optional callback to filter specific event instances
+     * @throws AssertionError if the event was emitted
      */
     assertNotEmitted<Event extends keyof EventsList | Constructor<any>>(event: Event, finder?: EventFinderCallback<EventsList, Event>): void;
     /**
-     * Assert a given event has been not been emitted
+     * Assert no events have been emitted
+     *
+     * @throws AssertionError if any events were emitted
      */
     assertNoneEmitted(): void;
     /**

package/build/src/tracing_channels.d.ts

@@ -0,0 +1,6 @@
+import diagnostics_channel from 'node:diagnostics_channel';
+import { type EventDispatchData } from './types.ts';
+/**
+ * Traces event.emit method calls
+ */
+export declare const eventDispatch: diagnostics_channel.TracingChannel<"adonisjs.event.dispatch", EventDispatchData>;

package/build/src/types.d.ts

@@ -5,13 +5,18 @@ import { type LazyImport, type Constructor } from '@poppinss/utils/types';
 export type AllowedEventTypes = string | symbol | number | Constructor<any>;
 /**
  * Data structure for a buffered event
+ *
+ * @template Event - The event type
+ * @template Data - The data type
  */
 export type BufferedEvent<Event, Data> = {
     event: Event;
     data: Data;
 };
 /**
- * Event list item inside bufferred items
+ * Event list item inside buffered items
+ *
+ * @template EventsList - The events list type
  */
 export type BufferedEventsList<EventsList> = {
     [Name in keyof EventsList]: BufferedEvent<Name, EventsList[Name]>;
@@ -20,21 +25,30 @@ export type BufferedEventsList<EventsList> = {
  * Representation of listener method on the listener class. The
  * spread args can type hint dependencies and container will
  * resolve them
+ *
+ * @template Data - The event data type
  */
 export type ListenerMethod<Data> = (data: Data, ...args: any[]) => any | Promise<any>;
 /**
  * The event listener defined as an inline callback
+ *
+ * @template Data - The event data type
  */
 export type ListenerFn<Data> = (data: Data) => any | Promise<any>;
 /**
  * Returns a union of methods from a listener that accepts
  * the event data as the first argument.
+ *
+ * @template Listener - The listener class constructor
+ * @template Data - The event data type
  */
 export type GetListenersMethods<Listener extends Constructor<any>, Data> = {
     [K in keyof InstanceType<Listener>]: InstanceType<Listener>[K] extends ListenerMethod<Data> ? K : never;
 }[keyof InstanceType<Listener>];
 /**
  * Representation of listener class with handle method
+ *
+ * @template Data - The event data type
  */
 export type ListenerClassWithHandleMethod<Data> = Constructor<{
     handle: ListenerMethod<Data>;
@@ -42,11 +56,16 @@ export type ListenerClassWithHandleMethod<Data> = Constructor<{
 /**
  * The event listener defined as an inline callback, string
  * listener class reference or a lazily imported listener
+ *
+ * @template Data - The event data type
+ * @template ListenerClass - The listener class constructor
  */
 export type Listener<Data, ListenerClass extends Constructor<any>> = ListenerFn<Data> | string | [LazyImport<ListenerClass> | ListenerClass, GetListenersMethods<ListenerClass, Data>?];
 /**
  * The EmitterLike interface exposes a less strict API to accept
  * emitter as an argument to emit events.
+ *
+ * @template EventsList - The events list type
  */
 export interface EmitterLike<EventsList extends Record<string | symbol | number, any>> {
     /**
@@ -54,6 +73,10 @@ export interface EmitterLike<EventsList extends Record<string | symbol | number,
      * in parallel.
      *
      * You can await this method to wait for events listeners to finish
+     *
+     * @param event - The event to emit
+     * @param data - The data to pass to listeners
+     * @returns Promise that resolves when all listeners finish
      */
     emit<Event extends Constructor<any>>(event: Event, data: InstanceType<Event>): Promise<void>;
     emit<Name extends keyof EventsList>(event: Name, data: EventsList[Name]): Promise<void>;
@@ -62,15 +85,32 @@ export interface EmitterLike<EventsList extends Record<string | symbol | number,
      * in the same sequence as they are registered.
      *
      * You can await this method to wait for events listeners to finish
+     *
+     * @param event - The event to emit
+     * @param data - The data to pass to listeners
+     * @returns Promise that resolves when all listeners finish
      */
     emitSerial<Event extends Constructor<any>>(event: Event, data: InstanceType<Event>): Promise<void>;
     emitSerial<Name extends keyof EventsList>(event: Name, data: EventsList[Name]): Promise<void>;
     /**
-     * Find if an event has one or more listeners
+     * Get count of listeners for a given event or all the events
+     *
+     * @param event - The event to count listeners for (optional)
+     * @returns The number of listeners
      */
     listenerCount(event?: keyof EventsList | Constructor<any>): number;
     /**
-     * Get count of listeners for a given event or all the events
+     * Find if an event has one or more listeners
+     *
+     * @param event - The event to check listeners for (optional)
+     * @returns True if the event has listeners
      */
     hasListeners(event?: keyof EventsList | Constructor<any>): boolean;
 }
+/**
+ * Data shared via the event.dispatch tracing channel
+ */
+export type EventDispatchData = {
+    event: AllowedEventTypes;
+    data: unknown;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adonisjs/events",
   "description": "An implementation of the event emitter built on top of emittery",
-  "version": "10.1.0-next.0",
+  "version": "10.1.0-next.2",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -36,27 +36,27 @@
     "quick:test": "node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts"
   },
   "devDependencies": {
-    "@adonisjs/application": "^9.0.0-next.1",
-    "@adonisjs/config": "^5.0.3",
-    "@adonisjs/eslint-config": "^3.0.0-next.0",
-    "@adonisjs/fold": "^10.2.0",
+    "@adonisjs/application": "^9.0.0-next.4",
+    "@adonisjs/config": "^6.0.0-next.1",
+    "@adonisjs/eslint-config": "^3.0.0-next.1",
+    "@adonisjs/fold": "^11.0.0-next.2",
     "@adonisjs/prettier-config": "^1.4.5",
     "@adonisjs/tsconfig": "^2.0.0-next.0",
     "@japa/assert": "^4.1.1",
     "@japa/expect-type": "^2.0.3",
     "@japa/file-system": "^2.3.2",
-    "@japa/runner": "^4.3.0",
-    "@poppinss/ts-exec": "^1.4.0",
+    "@japa/runner": "^4.4.0",
+    "@poppinss/ts-exec": "^1.4.1",
     "@release-it/conventional-changelog": "^10.0.1",
-    "@types/node": "^24.1.0",
+    "@types/node": "^24.3.0",
     "c8": "^10.1.3",
     "cross-env": "^10.0.0",
     "del-cli": "^6.0.0",
-    "eslint": "^9.32.0",
+    "eslint": "^9.34.0",
     "prettier": "^3.6.2",
     "release-it": "^19.0.4",
     "tsup": "^8.5.0",
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.2"
   },
   "dependencies": {
     "@poppinss/utils": "^7.0.0-next.3",
@@ -64,8 +64,8 @@
     "emittery": "^1.2.0"
   },
   "peerDependencies": {
-    "@adonisjs/application": "^9.0.0-next.1",
-    "@adonisjs/fold": "^10.0.1"
+    "@adonisjs/application": "^9.0.0-next.4",
+    "@adonisjs/fold": "^11.0.0-next.2"
   },
   "homepage": "https://github.com/adonisjs/events#readme",
   "repository": {