@adonisjs/events 8.4.9-4 → 9.0.0-0

package/README.md

@@ -2,7 +2,7 @@
 
 <br />
 
-[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url] [![synk-image]][synk-url]
+[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url]
 
 ## Introduction
 AdonisJS events is an implementation of the event emitter built on top of [emittery](https://github.com/sindresorhus/emittery). Alongside defining event listeners as inline callbacks, you can also bind modules to events and define events as classes.
@@ -32,6 +32,3 @@ AdonisJS events is open-sourced software licensed under the [MIT license](LICENS
 
 [license-image]: https://img.shields.io/npm/l/@adonisjs/events?color=blueviolet&style=for-the-badge
 [license-url]: LICENSE.md "license"
-
-[synk-image]: https://img.shields.io/snyk/vulnerabilities/github/adonisjs/events?label=Synk%20Vulnerabilities&style=for-the-badge
-[synk-url]: https://snyk.io/test/github/adonisjs/events?targetFile=package.json "synk"

package/build/chunk-VVJERWW5.js

@@ -0,0 +1,402 @@
+// src/emitter.ts
+import is2 from "@sindresorhus/is";
+import Emittery from "emittery";
+import { moduleExpression, moduleCaller, moduleImporter } from "@adonisjs/fold";
+
+// src/debug.ts
+import { debuglog } from "node:util";
+var debug_default = debuglog("adonisjs:events");
+
+// src/events_buffer.ts
+import is from "@sindresorhus/is";
+import { AssertionError } from "node:assert";
+var EventsBuffer = class {
+  /**
+   * Buffered events
+   */
+  #events = [];
+  /**
+   * Track emitted event
+   */
+  add(event, data) {
+    this.#events.push({ 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) {
+      const isClass = is.class(finder);
+      const message = typeof finder === "function" && !isClass ? `Expected callback to find an emitted event` : isClass ? `Expected "${finder.name}" event to be emitted` : `Expected "${String(finder)}" event to be emitted`;
+      throw new AssertionError({
+        message,
+        expected: true,
+        actual: false,
+        operator: "strictEqual",
+        stackStartFn: this.assertEmitted
+      });
+    }
+  }
+  /**
+   * Assert a given event has been not been emitted
+   */
+  assertNotEmitted(finder) {
+    const hasEvent = this.exists(finder);
+    if (hasEvent) {
+      const isClass = is.class(finder);
+      const message = typeof finder === "function" && !isClass ? `Expected callback to not find any event` : isClass ? `Expected "${finder.name}" event to be not emitted` : `Expected "${String(finder)}" event to be not emitted`;
+      throw new AssertionError({
+        message,
+        expected: false,
+        actual: true,
+        operator: "strictEqual",
+        stackStartFn: this.assertNotEmitted
+      });
+    }
+  }
+  /**
+   * Assert a given event has been not been emitted
+   */
+  assertNoneEmitted() {
+    const eventsSize = this.size();
+    if (eventsSize > 0) {
+      throw new AssertionError(
+        Object.assign(
+          {
+            message: `Expected zero events to be emitted. Instead received "${eventsSize}" event(s)`,
+            expected: 0,
+            actual: eventsSize,
+            operator: "strictEqual",
+            stackStartFn: this.assertNoneEmitted
+          },
+          {
+            showDiff: true
+          }
+        )
+      );
+    }
+  }
+  /**
+   * Flush events collected within memory
+   */
+  flush() {
+    this.#events = [];
+  }
+};
+
+// src/emitter.ts
+var Emitter = class {
+  /**
+   * Event classes to symbols mapping. We need symbols as emittery
+   * does not support class based event names
+   */
+  #eventsClassSymbols = /* @__PURE__ */ new Map();
+  /**
+   * A collection of events and their listeners. We do not track listeners
+   * listening for events only once
+   */
+  #eventsListeners = /* @__PURE__ */ 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 = /* @__PURE__ */ 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 (is2.class(event)) {
+      return this.#getEventClassSymbol(event);
+    }
+    return event;
+  }
+  /**
+   * Returns the event listeners map
+   */
+  #getEventListeners(event) {
+    if (!this.#eventsListeners.has(event)) {
+      this.#eventsListeners.set(event, /* @__PURE__ */ new Map());
+    }
+    return this.#eventsListeners.get(event);
+  }
+  /**
+   * Normalizes the event listener to a function that can be passed to
+   * emittery.
+   */
+  #normalizeEventListener(listener) {
+    if (typeof listener === "string") {
+      return moduleExpression(listener, this.#app.appRoot.toString()).toCallable(
+        this.#app.container
+      );
+    }
+    if (Array.isArray(listener)) {
+      const listenerModule = listener[0];
+      const method = listener[1] || "handle";
+      if (is2.class(listenerModule)) {
+        return moduleCaller(listenerModule, method).toCallable(this.#app.container);
+      }
+      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)) {
+      eventListeners.set(listener, this.#normalizeEventListener(listener));
+    }
+    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"]));
+  }
+  on(event, listener) {
+    if (debug_default.enabled) {
+      debug_default("registering event listener, event: %O, listener: %O", event, listener);
+    }
+    const normalizedEvent = this.#resolveEvent(event);
+    const normalizedListener = this.#resolveEventListener(event, listener);
+    this.#transport.on(normalizedEvent, normalizedListener);
+    return () => this.off(event, listener);
+  }
+  once(event, listener) {
+    if (debug_default.enabled) {
+      debug_default("registering one time event listener, event: %O, listener: %O", event, listener);
+    }
+    const normalizedEvent = this.#resolveEvent(event);
+    const normalizedListener = this.#normalizeEventListener(listener);
+    const off = this.#transport.on(normalizedEvent, async (data) => {
+      off();
+      debug_default("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) {
+    if (this.#eventsToFake.has(event) || this.#eventsToFake.has("*")) {
+      debug_default("faking emit. event: %O, data: %O", event, data);
+      this.#eventsBuffer.add(event, data);
+      return;
+    }
+    try {
+      const normalizedEvent = this.#resolveEvent(event);
+      await this.#transport.emit(normalizedEvent, data);
+    } catch (error) {
+      if (this.#errorHandler) {
+        this.#errorHandler(event, error, data);
+      } else {
+        throw error;
+      }
+    }
+  }
+  async emitSerial(event, data) {
+    if (this.#eventsToFake.has(event) || this.#eventsToFake.has("*")) {
+      debug_default("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_default.enabled) {
+      debug_default("removing listener, event: %O, listener: %O", event, listener);
+    }
+    const normalizedEvent = this.#resolveEvent(event);
+    const listeners = this.#getEventListeners(event);
+    const normalizedListener = listeners.get(listener);
+    if (!normalizedListener) {
+      return;
+    }
+    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_default("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_default("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) : void 0);
+  }
+  /**
+   * 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();
+    if (!events) {
+      debug_default("faking all events");
+      this.#eventsToFake.add("*");
+    } else {
+      debug_default("faking events: %O", events);
+      events.forEach((event) => this.#eventsToFake.add(event));
+    }
+    return this.#eventsBuffer;
+  }
+  /**
+   * Restore fakes
+   */
+  restore() {
+    debug_default("restoring existing fakes");
+    this.#eventsToFake.clear();
+    this.#eventsBuffer?.flush();
+    this.#eventsBuffer = void 0;
+  }
+};
+
+export {
+  Emitter
+};

package/build/{src/emitter.d.ts → emitter-253440aa.d.ts}

@@ -1,12 +1,59 @@
-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';
+import { Application } from '@adonisjs/application';
+import { UnsubscribeFunction } from 'emittery';
+import { AllowedEventTypes, BufferedEventsList, Constructor, BufferedEvent, Listener, ListenerMethod, ListenerClassWithHandleMethod, LazyImport } from './src/types.js';
+
+/**
+ * Exposes API to filter, find events from the events buffer.
+ */
+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;
+}
+
 /**
  * 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>> {
+declare class Emitter<EventsList extends Record<string | symbol | number, any>> {
     #private;
     /**
      * Returns a map of events and their registered listeners. The
@@ -105,3 +152,5 @@ export declare class Emitter<EventsList extends Record<string | symbol | number,
      */
     restore(): void;
 }
+
+export { Emitter as E };

package/build/factories/main.d.ts

@@ -1 +1,17 @@
-export { EmitterFactory } from './emitter.js';
+import { Application } from '@adonisjs/application';
+import { E as Emitter } from '../emitter-253440aa.js';
+import 'emittery';
+import '../src/types.js';
+
+/**
+ * Emitter factory is used to create an instance of emitter
+ * for testing
+ */
+declare class EmitterFactory {
+    /**
+     * Create emitter instance
+     */
+    create(app: Application<any>): Emitter<Record<string | number | symbol, any>>;
+}
+
+export { EmitterFactory };

package/build/factories/main.js

@@ -1,9 +1,16 @@
-/*
- * @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';
+import {
+  Emitter
+} from "../chunk-VVJERWW5.js";
+
+// factories/emitter.ts
+var EmitterFactory = class {
+  /**
+   * Create emitter instance
+   */
+  create(app) {
+    return new Emitter(app);
+  }
+};
+export {
+  EmitterFactory
+};

package/build/index.d.ts

@@ -1,2 +1,27 @@
-export { Emitter } from './src/emitter.js';
-export { BaseEvent } from './src/base_event.js';
+import { E as Emitter } from './emitter-253440aa.js';
+import '@adonisjs/application';
+import 'emittery';
+import './src/types.js';
+
+/**
+ * Base event adds ability to a class to act as an event. You can emit the
+ * event by calling "Event.dispatch" method.
+ */
+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>;
+}
+
+export { BaseEvent, Emitter };

package/build/index.js

@@ -1,10 +1,36 @@
-/*
- * @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';
+import {
+  Emitter
+} from "./chunk-VVJERWW5.js";
+
+// src/base_event.ts
+import { RuntimeException } from "@poppinss/utils";
+var BaseEvent = class {
+  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`
+      );
+    }
+    return this.emitter.emit(this, new this(...args));
+  }
+};
+export {
+  BaseEvent,
+  Emitter
+};

package/build/src/types.d.ts

@@ -1,28 +1,28 @@
 /**
  * Data types for event name
  */
-export type AllowedEventTypes = string | symbol | number | Constructor;
+type AllowedEventTypes = string | symbol | number | Constructor;
 /**
  * Class constructor type
  */
-export type Constructor<T = unknown> = new (...args: any[]) => T;
+type Constructor<T = unknown> = new (...args: any[]) => T;
 /**
  * A function that lazily imports a middleware
  */
-export type LazyImport<DefaultExport> = () => Promise<{
+type LazyImport<DefaultExport> = () => Promise<{
     default: DefaultExport;
 }>;
 /**
  * Data structure for a buffered event
  */
-export type BufferedEvent<Event, Data> = {
+type BufferedEvent<Event, Data> = {
     event: Event;
     data: Data;
 };
 /**
  * Event list item inside bufferred items
  */
-export type BufferedEventsList<EventsList> = {
+type BufferedEventsList<EventsList> = {
     [Name in keyof EventsList]: BufferedEvent<Name, EventsList[Name]>;
 }[keyof EventsList] | BufferedEvent<Constructor<any>, any>;
 /**
@@ -30,26 +30,28 @@ export type BufferedEventsList<EventsList> = {
  * spread args can type hint dependencies and container will
  * resolve them
  */
-export type ListenerMethod<Data> = (data: Data, ...args: any[]) => any | Promise<any>;
+type ListenerMethod<Data> = (data: Data, ...args: any[]) => any | Promise<any>;
 /**
  * The event listener defined as an inline callback
  */
-export type ListenerFn<Data> = (data: Data) => any | Promise<any>;
+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.
  */
-export type GetListenersMethods<Listener extends Constructor<any>, Data> = {
+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
  */
-export type ListenerClassWithHandleMethod<Data> = Constructor<{
+type ListenerClassWithHandleMethod<Data> = Constructor<{
     handle: ListenerMethod<Data>;
 }>;
 /**
  * The event listener defined as an inline callback, string
  * listener class reference or a lazily imported listener
  */
-export type Listener<Data, ListenerClass extends Constructor> = ListenerFn<Data> | string | [LazyImport<ListenerClass> | ListenerClass, GetListenersMethods<ListenerClass, Data>?];
+type Listener<Data, ListenerClass extends Constructor> = ListenerFn<Data> | string | [LazyImport<ListenerClass> | ListenerClass, GetListenersMethods<ListenerClass, Data>?];
+
+export { AllowedEventTypes, BufferedEvent, BufferedEventsList, Constructor, GetListenersMethods, LazyImport, Listener, ListenerClassWithHandleMethod, ListenerFn, ListenerMethod };

package/build/src/types.js

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