@adonisjs/events 8.4.9-2 → 8.4.9-3

package/build/factories/emitter.d.ts

@@ -1,6 +1,12 @@
 import type { Application } from '@adonisjs/application';
 import { Emitter } from '../src/emitter.js';
+/**
+ * Emitter factory is used to create an instance of emitter
+ * for testing
+ */
 export declare class EmitterFactory {
+    /**
+     * Create emitter instance
+     */
     create(app: Application<any>): Emitter<Record<string | number | symbol, any>>;
 }
-//# sourceMappingURL=emitter.d.ts.map

package/build/factories/emitter.js

@@ -1,5 +1,20 @@
+/*
+ * @adonisjs/events
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { Emitter } from '../src/emitter.js';
+/**
+ * Emitter factory is used to create an instance of emitter
+ * for testing
+ */
 export class EmitterFactory {
+    /**
+     * Create emitter instance
+     */
     create(app) {
         return new Emitter(app);
     }

package/build/factories/main.d.ts

@@ -1,2 +1 @@
 export { EmitterFactory } from './emitter.js';
-//# sourceMappingURL=main.d.ts.map

package/build/factories/main.js

@@ -1 +1,9 @@
+/*
+ * @adonisjs/events
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export { EmitterFactory } from './emitter.js';

package/build/index.d.ts

@@ -1,3 +1,2 @@
 export { Emitter } from './src/emitter.js';
 export { BaseEvent } from './src/base_event.js';
-//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -1,2 +1,10 @@
+/*
+ * @adonisjs/events
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export { Emitter } from './src/emitter.js';
 export { BaseEvent } from './src/base_event.js';

package/build/src/base_event.d.ts

@@ -1,8 +1,21 @@
 import type { Emitter } from './emitter.js';
+/**
+ * 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 {
     constructor(..._: any[]);
+    /**
+     * The emitter to use for dispatching events
+     */
     static emitter?: Emitter<any>;
+    /**
+     * Specify the emitter instance to use for dispatching events
+     */
     static useEmitter(emitter: Emitter<any>): void;
+    /**
+     * Dispatch the current class as an event. The method takes the arguments
+     * accepted by the class constructor.
+     */
     static dispatch<T extends typeof BaseEvent>(this: T, ...args: ConstructorParameters<T>): Promise<void>;
 }
-//# sourceMappingURL=base_event.d.ts.map

package/build/src/base_event.js

@@ -1,10 +1,32 @@
+/*
+ * @adonisjs/events
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { RuntimeException } from '@poppinss/utils';
+/**
+ * Base event adds ability to a class to act as an event. You can emit the
+ * event by calling "Event.dispatch" method.
+ */
 export class BaseEvent {
     constructor(..._) { }
+    /**
+     * The emitter to use for dispatching events
+     */
     static emitter;
+    /**
+     * Specify the emitter instance to use for dispatching events
+     */
     static useEmitter(emitter) {
         this.emitter = emitter;
     }
+    /**
+     * Dispatch the current class as an event. The method takes the arguments
+     * accepted by the class constructor.
+     */
     static async dispatch(...args) {
         if (!this.emitter) {
             throw new RuntimeException(`Cannot dispatch "${this.name}" event. Make sure to pass emitter to the "BaseEvent" class for dispatch method to work`);

package/build/src/debug.d.ts

@@ -1,4 +1,3 @@
 /// <reference types="node" resolution-mode="require"/>
 declare const _default: import("util").DebugLogger;
 export default _default;
-//# sourceMappingURL=debug.d.ts.map

package/build/src/debug.js

@@ -1,2 +1,10 @@
+/*
+ * @adonisjs/events
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { debuglog } from 'node:util';
 export default debuglog('adonisjs:events');

package/build/src/emitter.d.ts

@@ -2,27 +2,106 @@ import type { Application } from '@adonisjs/application';
 import { type UnsubscribeFunction } from 'emittery';
 import { EventsBuffer } from './events_buffer.js';
 import type { Listener, LazyImport, Constructor, ListenerMethod, AllowedEventTypes, ListenerClassWithHandleMethod } from './types.js';
+/**
+ * Event emitter is built on top of emittery with support class based
+ * events and listeners
+ */
 export declare class Emitter<EventsList extends Record<string | symbol | number, any>> {
     #private;
+    /**
+     * Returns a map of events and their registered listeners. The
+     * map key is the event name and the value is another map
+     * of listeners.
+     *
+     * The listeners map key is the original binding listener
+     * and the value is a callback function.
+     */
     get eventsListeners(): Map<AllowedEventTypes, Map<Listener<any, Constructor<any>>, ListenerMethod<any>>>;
     constructor(app: Application<any>);
+    /**
+     * Register a global error handler
+     */
     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.
+     */
     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.
+     */
     on<Event extends Constructor, ListenerClass extends Constructor>(event: Event, listener: Listener<InstanceType<Event>, ListenerClass>): UnsubscribeFunction;
     on<Name extends keyof EventsList, ListenerClass extends Constructor>(event: Name, listener: Listener<EventsList[Name], ListenerClass>): UnsubscribeFunction;
+    /**
+     * Listen for an event only once
+     */
     once<Event extends Constructor, ListenerClass extends Constructor>(event: Event, listener: Listener<InstanceType<Event>, ListenerClass>): void;
     once<Name extends keyof EventsList, ListenerClass extends Constructor>(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.
+     */
     onAny(listener: (event: AllowedEventTypes, data: any) => any | Promise<any>): UnsubscribeFunction;
+    /**
+     * Emit event. The event listeners will be called asynchronously
+     * in parallel.
+     *
+     * You can await this method to wait for events listeners to 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>;
+    /**
+     * Emit events serially. The event listeners will be called asynchronously
+     * in the same sequence as they are registered.
+     *
+     * You can await this method to wait for events listeners to 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>;
+    /**
+     * Remove a specific listener for an event
+     */
     off(event: keyof EventsList | Constructor<any>, listener: Listener<any, Constructor<any>>): void;
+    /**
+     * Remove a specific listener listening for all the events
+     */
     offAny(listener: (event: keyof EventsList | Constructor<any>, data: any) => any | Promise<any>): this;
+    /**
+     * Remove a specific listener for an event
+     *
+     * @alias "off"
+     */
     clearListener(event: keyof EventsList | Constructor<any>, listener: Listener<any, Constructor<any>>): void;
+    /**
+     * Clear all listeners for a specific event
+     */
     clearListeners(event: keyof EventsList | Constructor<any>): void;
+    /**
+     * Clear all listeners for all the events
+     */
     clearAllListeners(): void;
+    /**
+     * Get count of listeners for a given event or all the events
+     */
     listenerCount(event?: keyof EventsList | Constructor<any>): number;
+    /**
+     * Find if an event has one or more listeners
+     */
     hasListeners(event?: keyof EventsList | Constructor<any>): boolean;
+    /**
+     * Fake one or more events. The listeners for faked events will
+     * not be invoked.
+     *
+     * The return value is an events buffer that collects all the
+     * events within memory.
+     *
+     * Calling this method one than once drops the existing fakes and
+     * creates new one.
+     */
     fake(events?: (keyof EventsList | Constructor<any>)[]): EventsBuffer<EventsList>;
+    /**
+     * Restore fakes
+     */
     restore(): void;
 }
-//# sourceMappingURL=emitter.d.ts.map

package/build/src/emitter.js

@@ -1,54 +1,130 @@
+/*
+ * @adonisjs/events
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import is from '@sindresorhus/is';
 import Emittery from 'emittery';
 import { moduleExpression, moduleCaller, moduleImporter } from '@adonisjs/fold';
 import debug from './debug.js';
 import { EventsBuffer } from './events_buffer.js';
+/**
+ * Event emitter is built on top of emittery with support class based
+ * events and listeners
+ */
 export class Emitter {
+    /**
+     * Event classes to symbols mapping. We need symbols as emittery
+     * does not support class based event names
+     */
     #eventsClassSymbols = new Map();
+    /**
+     * A collection of events and their listeners. We do not track listeners
+     * listening for events only once
+     */
     #eventsListeners = new Map();
+    /**
+     * Underlying transport to emit events
+     */
     #transport = new Emittery();
+    /**
+     * Events buffer. The events are collected inside an in-memory
+     * buffer during fakes
+     */
     #eventsBuffer;
+    /**
+     * A set of events to fake
+     */
     #eventsToFake = new Set();
+    /**
+     * Error handler to catch all errors thrown by listeners
+     */
     #errorHandler;
+    /**
+     * Reference to AdonisJS application, we need the application root
+     * and container reference from it.
+     */
     #app;
+    /**
+     * Returns a map of events and their registered listeners. The
+     * map key is the event name and the value is another map
+     * of listeners.
+     *
+     * The listeners map key is the original binding listener
+     * and the value is a callback function.
+     */
     get eventsListeners() {
         return this.#eventsListeners;
     }
     constructor(app) {
         this.#app = app;
     }
+    /**
+     * Returns the symbol for a class based event.
+     */
     #getEventClassSymbol(event) {
         if (!this.#eventsClassSymbols.has(event)) {
             this.#eventsClassSymbols.set(event, Symbol(event.name));
         }
         return this.#eventsClassSymbols.get(event);
     }
+    /**
+     * Normalizes the event to emittery supported data types. The class
+     * constructors are cached against a unique symbol.
+     */
     #resolveEvent(event) {
         if (is.class_(event)) {
             return this.#getEventClassSymbol(event);
         }
         return event;
     }
+    /**
+     * Returns the event listeners map
+     */
     #getEventListeners(event) {
         if (!this.#eventsListeners.has(event)) {
             this.#eventsListeners.set(event, new Map());
         }
         return this.#eventsListeners.get(event);
     }
+    /**
+     * Normalizes the event listener to a function that can be passed to
+     * emittery.
+     */
     #normalizeEventListener(listener) {
+        /**
+         * Parse string based listener
+         */
         if (typeof listener === 'string') {
-            return moduleExpression(listener, this.#app.appRoot).toCallable(this.#app.container);
+            return moduleExpression(listener, this.#app.appRoot.toString()).toCallable(this.#app.container);
         }
+        /**
+         * Parse array based listener with the listener reference
+         * or lazily imported listener class
+         */
         if (Array.isArray(listener)) {
             const listenerModule = listener[0];
             const method = listener[1] || 'handle';
+            /**
+             * Class reference
+             */
             if (is.class_(listenerModule)) {
                 return moduleCaller(listenerModule, method).toCallable(this.#app.container);
             }
+            /**
+             * Lazily loaded module
+             */
             return moduleImporter(listenerModule, method).toCallable(this.#app.container);
         }
         return listener;
     }
+    /**
+     * Resolves the event listener either from the cache or normalizes
+     * it and stores it inside the cache
+     */
     #resolveEventListener(event, listener) {
         const eventListeners = this.#getEventListeners(event);
         if (!eventListeners.has(listener)) {
@@ -56,10 +132,18 @@ export class Emitter {
         }
         return eventListeners.get(listener);
     }
+    /**
+     * Register a global error handler
+     */
     onError(callback) {
         this.#errorHandler = callback;
         return 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.
+     */
     listen(event, listeners) {
         listeners.forEach((listener) => this.on(event, [listener, 'handle']));
     }
@@ -78,16 +162,30 @@ export class Emitter {
         }
         const normalizedEvent = this.#resolveEvent(event);
         const normalizedListener = this.#normalizeEventListener(listener);
+        /**
+         * Listening for an event and unsubscribing right after the event is emitted.
+         * Internally emittery does the same thing, but they do not await the
+         * handler. Therefore, the "once" listeners will finish after the
+         * "emit" call. This behavior is not inline with the "on" event
+         * listeners.
+         */
         const off = this.#transport.on(normalizedEvent, async (data) => {
             off();
             debug('removing one time event listener, event: %O', event);
             await normalizedListener(data);
         });
     }
+    /**
+     * Attach a listener to listen for all the events. Wildcard listeners
+     * can only be defined as inline callbacks.
+     */
     onAny(listener) {
         return this.#transport.onAny(listener);
     }
     async emit(event, data) {
+        /**
+         * Entertain fakes if exists
+         */
         if (this.#eventsToFake.has(event) || this.#eventsToFake.has('*')) {
             debug('faking emit. event: %O, data: %O', event, data);
             this.#eventsBuffer.add(event, data);
@@ -106,6 +204,31 @@ export class Emitter {
             }
         }
     }
+    async emitSerial(event, data) {
+        /**
+         * Entertain fakes if exists
+         */
+        if (this.#eventsToFake.has(event) || this.#eventsToFake.has('*')) {
+            debug('faking emit. event: %O, data: %O', event, data);
+            this.#eventsBuffer.add(event, data);
+            return;
+        }
+        try {
+            const normalizedEvent = this.#resolveEvent(event);
+            await this.#transport.emitSerial(normalizedEvent, data);
+        }
+        catch (error) {
+            if (this.#errorHandler) {
+                this.#errorHandler(event, error, data);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Remove a specific listener for an event
+     */
     off(event, listener) {
         if (debug.enabled) {
             debug('removing listener, event: %O, listener: %O', event, listener);
@@ -119,29 +242,59 @@ export class Emitter {
         listeners.delete(listener);
         this.#transport.off(normalizedEvent, normalizedListener);
     }
+    /**
+     * Remove a specific listener listening for all the events
+     */
     offAny(listener) {
         this.#transport.offAny(listener);
         return this;
     }
+    /**
+     * Remove a specific listener for an event
+     *
+     * @alias "off"
+     */
     clearListener(event, listener) {
         return this.off(event, listener);
     }
+    /**
+     * Clear all listeners for a specific event
+     */
     clearListeners(event) {
         debug('clearing all listeners for event %O', event);
         this.#transport.clearListeners(this.#resolveEvent(event));
         this.#eventsListeners.delete(event);
     }
+    /**
+     * Clear all listeners for all the events
+     */
     clearAllListeners() {
         debug('clearing all event listeners');
         this.#transport.clearListeners();
         this.#eventsListeners.clear();
     }
+    /**
+     * Get count of listeners for a given event or all the events
+     */
     listenerCount(event) {
         return this.#transport.listenerCount(event ? this.#resolveEvent(event) : undefined);
     }
+    /**
+     * Find if an event has one or more listeners
+     */
     hasListeners(event) {
         return this.listenerCount(event) > 0;
     }
+    /**
+     * Fake one or more events. The listeners for faked events will
+     * not be invoked.
+     *
+     * The return value is an events buffer that collects all the
+     * events within memory.
+     *
+     * Calling this method one than once drops the existing fakes and
+     * creates new one.
+     */
     fake(events) {
         this.restore();
         this.#eventsBuffer = new EventsBuffer();
@@ -155,6 +308,9 @@ export class Emitter {
         }
         return this.#eventsBuffer;
     }
+    /**
+     * Restore fakes
+     */
     restore() {
         debug('restoring existing fakes');
         this.#eventsToFake.clear();

package/build/src/events_buffer.d.ts

@@ -1,15 +1,47 @@
 import type { AllowedEventTypes, BufferedEvent, BufferedEventsList, Constructor } from './types.js';
+/**
+ * Exposes API to filter, find events from the events buffer.
+ */
 export declare class EventsBuffer<EventsList extends Record<string | symbol | number, any>> {
     #private;
+    /**
+     * Track emitted event
+     */
     add<Name extends AllowedEventTypes>(event: Name, data: any): void;
+    /**
+     * Get all the emitted events
+     */
     all(): BufferedEventsList<EventsList>[];
+    /**
+     * Returns the size of captured events
+     */
     size(): number;
+    /**
+     * Find if an event was emitted
+     */
     exists<Event extends keyof EventsList | Constructor>(finder: Event | ((event: BufferedEventsList<EventsList>) => boolean)): boolean;
+    /**
+     * Get selected events
+     */
     filter(finder: keyof EventsList | Constructor | ((event: BufferedEventsList<EventsList>) => boolean)): BufferedEventsList<EventsList>[];
+    /**
+     * Find a specific event
+     */
     find<Event extends keyof EventsList | Constructor>(finder: Event | ((event: BufferedEventsList<EventsList>) => boolean)): (Event extends keyof EventsList ? BufferedEvent<Event, EventsList[Event]> : Event extends Constructor<infer A> ? BufferedEvent<Event, A> : BufferedEventsList<EventsList>) | null;
+    /**
+     * Assert a given event has been emitted
+     */
     assertEmitted<Event extends keyof EventsList | Constructor>(finder: Event | ((event: BufferedEventsList<EventsList>) => boolean)): void;
+    /**
+     * Assert a given event has been not been emitted
+     */
     assertNotEmitted<Event extends keyof EventsList | Constructor<any>>(finder: Event | ((event: BufferedEventsList<EventsList>) => boolean)): void;
+    /**
+     * Assert a given event has been not been emitted
+     */
     assertNoneEmitted(): void;
+    /**
+     * Flush events collected within memory
+     */
     flush(): void;
 }
-//# sourceMappingURL=events_buffer.d.ts.map

package/build/src/events_buffer.js

@@ -1,31 +1,66 @@
+/*
+ * @adonisjs/events
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import is from '@sindresorhus/is';
 import { AssertionError } from 'node:assert';
+/**
+ * Exposes API to filter, find events from the events buffer.
+ */
 export class EventsBuffer {
+    /**
+     * Buffered events
+     */
     #events = [];
+    /**
+     * Track emitted event
+     */
     add(event, data) {
         this.#events.push({ event: event, data });
     }
+    /**
+     * Get all the emitted events
+     */
     all() {
         return this.#events;
     }
+    /**
+     * Returns the size of captured events
+     */
     size() {
         return this.#events.length;
     }
+    /**
+     * Find if an event was emitted
+     */
     exists(finder) {
         return !!this.find(finder);
     }
+    /**
+     * Get selected events
+     */
     filter(finder) {
         if (typeof finder === 'function' && !is.class_(finder)) {
             return this.#events.filter(finder);
         }
         return this.#events.filter((event) => event.event === finder);
     }
+    /**
+     * Find a specific event
+     */
     find(finder) {
         if (typeof finder === 'function' && !is.class_(finder)) {
             return (this.#events.find(finder) || null);
         }
         return (this.#events.find((event) => event.event === finder) || null);
     }
+    /**
+     * Assert a given event has been emitted
+     */
     assertEmitted(finder) {
         const hasEvent = this.exists(finder);
         if (!hasEvent) {
@@ -44,6 +79,9 @@ export class EventsBuffer {
             });
         }
     }
+    /**
+     * Assert a given event has been not been emitted
+     */
     assertNotEmitted(finder) {
         const hasEvent = this.exists(finder);
         if (hasEvent) {
@@ -62,6 +100,9 @@ export class EventsBuffer {
             });
         }
     }
+    /**
+     * Assert a given event has been not been emitted
+     */
     assertNoneEmitted() {
         const eventsSize = this.size();
         if (eventsSize > 0) {
@@ -76,6 +117,9 @@ export class EventsBuffer {
             }));
         }
     }
+    /**
+     * Flush events collected within memory
+     */
     flush() {
         this.#events = [];
     }