@h3ravel/events 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 h3ravel
+
+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,43 @@
+<div align="center">
+  <a href="https://h3ravel.toneflix.net"  target="_blank">
+    <img src="https://raw.githubusercontent.com/h3ravel/assets/refs/heads/main/logo-full.svg" width="200" alt="H3ravel Logo">
+  </a>
+  <h1 align="center"><a href="https://h3ravel.toneflix.net/events">H3ravel Events</a></h1>
+
+[![Framework][ix]][lx]
+[![Events Package Version][i1]][l1]
+[![Downloads][d1]][d1]
+[![Tests][tei]][tel]
+[![License][lini]][linl]
+
+</div>
+
+# About H3ravel/events
+
+This is the events handling system for the [H3ravel](https://h3ravel.toneflix.net) framework.
+
+## Contributing
+
+Thank you for considering contributing to the H3ravel framework! The [Contribution Guide](https://h3ravel.toneflix.net/contributing) can be found in the H3ravel documentation and will provide you with all the information you need to get started.
+
+## Code of Conduct
+
+In order to ensure that the H3ravel community is welcoming to all, please review and abide by the [Code of Conduct](#).
+
+## Security Vulnerabilities
+
+If you discover a security vulnerability within H3ravel, please send an e-mail to Legacy via hamzas.legacy@toneflix.ng. All security vulnerabilities will be promptly addressed.
+
+## License
+
+The H3ravel framework is open-sourced software licensed under the [MIT license](LICENSE).
+
+[ix]: https://img.shields.io/npm/v/%40h3ravel%2Fcore?style=flat-square&label=Framework&color=%230970ce
+[lx]: https://www.npmjs.com/package/@h3ravel/core
+[i1]: https://img.shields.io/npm/v/%40h3ravel%2Fevents?style=flat-square&label=@h3ravel/events&color=%230970ce
+[l1]: https://www.npmjs.com/package/@h3ravel/events
+[d1]: https://img.shields.io/npm/dt/%40h3ravel%2Fevents?style=flat-square&label=Downloads&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40h3ravel%2Fevents
+[linl]: https://github.com/h3ravel/framework/blob/main/LICENSE
+[lini]: https://img.shields.io/github/license/h3ravel/framework
+[tel]: https://github.com/h3ravel/framework/actions/workflows/test.yml
+[tei]: https://github.com/h3ravel/framework/actions/workflows/test.yml/badge.svg

package/dist/index.cjs

@@ -0,0 +1,346 @@
+let __h3ravel_support = require("@h3ravel/support");
+let __h3ravel_core = require("@h3ravel/core");
+let __h3ravel_contracts = require("@h3ravel/contracts");
+
+//#region src/Dispatcher.ts
+var Dispatcher = class {
+	/**
+	* The IoC container instance.
+	*/
+	container;
+	/**
+	* The registered event listeners.
+	*/
+	listeners = {};
+	/**
+	* The wildcard listeners.
+	*/
+	wildcards = {};
+	/**
+	* The cached wildcard listeners.
+	*/
+	wildcardsCache = {};
+	/**
+	* The queue resolver instance.
+	*/
+	queueResolver;
+	/**
+	* The database transaction manager resolver instance.
+	*/
+	transactionManagerResolver;
+	/**
+	* The currently deferred events.
+	*/
+	deferredEvents = {};
+	/**
+	* Indicates if events should be deferred.
+	*/
+	deferringEvents = false;
+	/**
+	* The specific events to defer (null means defer all events).
+	*/
+	eventsToDefer;
+	/**
+	* Create a new event dispatcher instance.
+	*/
+	constructor(container) {
+		this.container = container ?? new __h3ravel_core.Container();
+	}
+	/**
+	* Register an event listener with the dispatcher.
+	*
+	* @param  events
+	* @param listener
+	*/
+	listen(events, listener) {
+		for (const event of __h3ravel_support.Arr.wrap(events)) if (typeof event === "string" && listener) if (event.includes("*")) this.setupWildcardListen(event, listener);
+		else this.listeners[event].push(listener);
+		else if (typeof event === "function") event(listener);
+		else if (typeof listener === "function") listener();
+	}
+	/**
+	* Setup a wildcard listener callback.
+	*
+	* @param  event
+	* @param  listener
+	*/
+	setupWildcardListen(event, listener) {
+		this.wildcards[event].push(listener);
+		this.wildcardsCache = {};
+	}
+	/**
+	* Determine if a given event has listeners.
+	*
+	* @param  eventName
+	* @return bool
+	*/
+	hasListeners(eventName) {
+		return this.listeners[eventName] || this.wildcards[eventName] || this.hasWildcardListeners(eventName);
+	}
+	/**
+	* Determine if the given event has any wildcard listeners.
+	*
+	* @param  eventName
+	*/
+	hasWildcardListeners(eventName) {
+		for (const [key] of Object.entries(this.wildcards)) if (__h3ravel_support.Str.is(key, eventName)) return true;
+		return false;
+	}
+	/**
+	* Register an event and payload to be fired later.
+	*
+	* @para  event
+	* @param payload
+	* @return void
+	*/
+	push(event, payload = []) {
+		this.listen(event + "_pushed", () => {
+			this.dispatch(event, payload);
+		});
+	}
+	/**
+	* Flush a set of pushed events.
+	*
+	* @param event
+	*/
+	flush(event) {
+		this.dispatch(event + "_pushed");
+	}
+	/**
+	* Resolve the subscriber instance.
+	*
+	* @param  subscriber
+	*/
+	resolveSubscriber(subscriber) {
+		if (typeof subscriber === "string") return this.container.make(subscriber);
+		return subscriber;
+	}
+	/**
+	* Fire an event until the first non-null response is returned.
+	*
+	* @param event
+	* @param  mixed  payload
+	* @return mixed
+	*/
+	until(event, payload = {}) {
+		return this.dispatch(event, payload, true);
+	}
+	/**
+	* Fire an event and call the listeners.
+	*
+	* @param event
+	* @param payload
+	* @param halt
+	*/
+	dispatch(event, _payload = [], _halt = false) {}
+	/**
+	* Remove a set of listeners from the dispatcher.
+	*
+	* @param  event
+	*/
+	forget(event) {
+		if (event.includes("*")) delete this.wildcards[event];
+		else delete this.listeners[event];
+		for (const [key] of Object.entries(this.wildcardsCache)) if (__h3ravel_support.Str.is(event, key)) delete this.wildcardsCache[key];
+	}
+	/**
+	* Forget all of the pushed listeners.
+	*
+	* @return void
+	*/
+	forgetPushed() {
+		for (const [key] of Object.entries(this.listeners)) if (key.endsWith("_pushed")) this.forget(key);
+	}
+	/**
+	* Get the queue implementation from the resolver.
+	*/
+	resolveQueue() {
+		return this.queueResolver?.();
+	}
+	/**
+	* Set the queue resolver implementation.
+	*
+	* @param  callable  $resolver
+	* @return this
+	*/
+	setQueueResolver(resolver) {
+		this.queueResolver = resolver;
+		return this;
+	}
+	/**
+	* Get the database transaction manager implementation from the resolver.
+	*/
+	resolveTransactionManager() {
+		return this.transactionManagerResolver?.();
+	}
+	/**
+	* Set the database transaction manager resolver implementation.
+	*
+	* @param resolver
+	*/
+	setTransactionManagerResolver(resolver) {
+		this.transactionManagerResolver = resolver;
+		return this;
+	}
+	/**
+	* Execute the given callback while deferring events, then dispatch all deferred events.
+	*
+	* @param  callback
+	* @param  events
+	*/
+	defer(callback, events) {
+		const wasDeferring = this.deferringEvents;
+		const previousDeferredEvents = this.deferredEvents;
+		const previousEventsToDefer = this.eventsToDefer;
+		this.deferringEvents = true;
+		this.deferredEvents = {};
+		this.eventsToDefer = events;
+		try {
+			const result = callback();
+			this.deferringEvents = false;
+			for (const args of Object.entries(this.deferredEvents)) this.dispatch(...args);
+			return result;
+		} finally {
+			this.deferringEvents = wasDeferring;
+			this.deferredEvents = previousDeferredEvents;
+			this.eventsToDefer = previousEventsToDefer;
+		}
+	}
+	/**
+	* Determine if the given event should be deferred.
+	*
+	* @param  event
+	*/
+	shouldDeferEvent(event) {
+		return this.deferringEvents && (this.eventsToDefer === null || this.eventsToDefer?.includes(event));
+	}
+	/**
+	* Gets the raw, unprepared listeners.
+	*
+	* @return array
+	*/
+	getRawListeners() {
+		return this.listeners;
+	}
+};
+
+//#endregion
+//#region src/Providers/EventsServiceProvider.ts
+/**
+* Events handling.
+*/
+var EventsServiceProvider = class extends __h3ravel_core.ServiceProvider {
+	static priority = 992;
+	static order = "before:RouteServiceProvider";
+	register() {
+		this.app.singleton("app.events", (app) => {
+			return new Dispatcher(app).setQueueResolver(() => {}).setTransactionManagerResolver(function() {});
+		});
+		this.app.alias([
+			["events", "app.events"],
+			[Dispatcher, "app.events"],
+			[__h3ravel_contracts.IDispatcher, "app.events"]
+		]);
+	}
+};
+
+//#endregion
+//#region src/QueuedListenerCalller.ts
+var QueuedListenerCalller = class {
+	/**
+	* The underlying queue job instance.
+	*/
+	job;
+	/**
+	* The listener class.
+	*/
+	className;
+	/**
+	* The listener method.
+	*/
+	method;
+	/**
+	* The data to be passed to the listener.
+	*/
+	data;
+	/**
+	* The number of times the job may be attempted.
+	*/
+	tries;
+	/**
+	* The maximum number of exceptions allowed, regardless of attempts.
+	*/
+	maxExceptions;
+	/**
+	* The number of seconds to wait before retrying a job that encountered an uncaught exception.
+	*/
+	backoff;
+	/**
+	* The timestamp indicating when the job should timeout.
+	*/
+	retryUntil;
+	/**
+	* The number of seconds the job can run before timing out.
+	*/
+	timeout;
+	/**
+	* Indicates if the job should fail if the timeout is exceeded.
+	*/
+	failOnTimeout = false;
+	/**
+	* Indicates if the job should be encrypted.
+	*/
+	shouldBeEncrypted = false;
+	/**
+	* Create a new job instance.
+	*
+	* @param  class
+	* @param method
+	* @param data
+	*/
+	constructor(className, method, data) {
+		this.data = data;
+		this.className = className;
+		this.method = method;
+	}
+	/**
+	* Handle the queued job.
+	*/
+	handle(_container) {}
+	/**
+	* Set the job instance of the given class if necessary.
+	*
+	* @param  job
+	* @param  instance
+	*/
+	setJobInstanceIfNecessary(job, instance) {
+		return {};
+	}
+	/**
+	* Call the failed method on the job instance.
+	*
+	* The event instance and the exception will be passed.
+	*
+	* @param  e
+	*/
+	failed(_e) {}
+	/**
+	* Unserialize the data if needed.
+	*
+	* @return void
+	*/
+	prepareData() {}
+	/**
+	* Get the display name for the queued job.
+	*
+	* @return string
+	*/
+	displayName() {
+		return this.className;
+	}
+};
+
+//#endregion
+exports.Dispatcher = Dispatcher;
+exports.EventsServiceProvider = EventsServiceProvider;
+exports.QueuedListenerCalller = QueuedListenerCalller;

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+/// <reference path="./app.globals.d.ts" />
+import { Container, ServiceProvider } from "@h3ravel/core";
+import { IJob } from "@h3ravel/contracts";
+
+//#region src/Contracts/EventsContract.d.ts
+type ListenerClassConstructor = (new (...args: any) => any) & {
+  subscribe?(...args: any[]): any;
+};
+type AppEvent = (...args: any[]) => any;
+type AppListener = (...args: any[]) => any;
+//#endregion
+//#region src/Dispatcher.d.ts
+declare class Dispatcher {
+  /**
+   * The IoC container instance.
+   */
+  protected container: Container;
+  /**
+   * The registered event listeners.
+   */
+  protected listeners: Record<string, any[]>;
+  /**
+   * The wildcard listeners.
+   */
+  protected wildcards: Record<string, any[]>;
+  /**
+   * The cached wildcard listeners.
+   */
+  protected wildcardsCache: Record<string, any[]>;
+  /**
+   * The queue resolver instance.
+   */
+  protected queueResolver?: (...a: any[]) => any;
+  /**
+   * The database transaction manager resolver instance.
+   */
+  protected transactionManagerResolver?: (...a: any[]) => any;
+  /**
+   * The currently deferred events.
+   */
+  protected deferredEvents: Record<string, any[]>;
+  /**
+   * Indicates if events should be deferred.
+   */
+  protected deferringEvents: boolean;
+  /**
+   * The specific events to defer (null means defer all events).
+   */
+  protected eventsToDefer?: AppEvent[];
+  /**
+   * Create a new event dispatcher instance.
+   */
+  constructor(container: Container);
+  /**
+   * Register an event listener with the dispatcher.
+   *
+   * @param  events
+   * @param listener
+   */
+  listen(events: AppEvent | AppEvent[] | string | string[], listener?: AppListener | AppListener[] | string | string[]): void;
+  /**
+   * Setup a wildcard listener callback.
+   *
+   * @param  event
+   * @param  listener
+   */
+  protected setupWildcardListen(event: string, listener: AppListener | AppListener[] | string | string[]): void;
+  /**
+   * Determine if a given event has listeners.
+   *
+   * @param  eventName
+   * @return bool
+   */
+  hasListeners(eventName: string): any[];
+  /**
+   * Determine if the given event has any wildcard listeners.
+   *
+   * @param  eventName
+   */
+  hasWildcardListeners(eventName: string): boolean;
+  /**
+   * Register an event and payload to be fired later.
+   *
+   * @para  event
+   * @param payload
+   * @return void
+   */
+  push(event: string, payload?: Record<string, any> | any[]): void;
+  /**
+   * Flush a set of pushed events.
+   *
+   * @param event
+   */
+  flush(event: string): void;
+  /**
+   * Resolve the subscriber instance.
+   *
+   * @param  subscriber
+   */
+  protected resolveSubscriber(subscriber: string | ListenerClassConstructor): any;
+  /**
+   * Fire an event until the first non-null response is returned.
+   *
+   * @param event
+   * @param  mixed  payload
+   * @return mixed
+   */
+  until(event: AppEvent, payload?: {}): void;
+  /**
+   * Fire an event and call the listeners.
+   *
+   * @param event
+   * @param payload
+   * @param halt
+   */
+  dispatch(event: Record<string, any> | string, _payload?: Record<string, any> | any[], _halt?: boolean): void;
+  /**
+   * Remove a set of listeners from the dispatcher.
+   *
+   * @param  event
+   */
+  forget(event: string): void;
+  /**
+   * Forget all of the pushed listeners.
+   *
+   * @return void
+   */
+  forgetPushed(): void;
+  /**
+   * Get the queue implementation from the resolver.
+   */
+  protected resolveQueue(): any;
+  /**
+   * Set the queue resolver implementation.
+   *
+   * @param  callable  $resolver
+   * @return this
+   */
+  setQueueResolver(resolver: (...a: any[]) => any): this;
+  /**
+   * Get the database transaction manager implementation from the resolver.
+   */
+  protected resolveTransactionManager(): any;
+  /**
+   * Set the database transaction manager resolver implementation.
+   *
+   * @param resolver
+   */
+  setTransactionManagerResolver(resolver: (...a: any[]) => any): this;
+  /**
+   * Execute the given callback while deferring events, then dispatch all deferred events.
+   *
+   * @param  callback
+   * @param  events
+   */
+  defer(callback: (...a: any[]) => any, events: AppEvent[]): any;
+  /**
+   * Determine if the given event should be deferred.
+   *
+   * @param  event
+   */
+  protected shouldDeferEvent(event: AppEvent): boolean | undefined;
+  /**
+   * Gets the raw, unprepared listeners.
+   *
+   * @return array
+   */
+  getRawListeners(): Record<string, any[]>;
+}
+//#endregion
+//#region src/Providers/EventsServiceProvider.d.ts
+/**
+ * Events handling.
+ */
+declare class EventsServiceProvider extends ServiceProvider {
+  static priority: number;
+  static order: string;
+  register(): void;
+}
+//#endregion
+//#region src/QueuedListenerCalller.d.ts
+declare class QueuedListenerCalller {
+  /**
+   * The underlying queue job instance.
+   */
+  job: IJob;
+  /**
+   * The listener class.
+   */
+  className: ListenerClassConstructor;
+  /**
+   * The listener method.
+   */
+  method: string;
+  /**
+   * The data to be passed to the listener.
+   */
+  data: Record<string, any>;
+  /**
+   * The number of times the job may be attempted.
+   */
+  tries?: number;
+  /**
+   * The maximum number of exceptions allowed, regardless of attempts.
+   */
+  maxExceptions?: number;
+  /**
+   * The number of seconds to wait before retrying a job that encountered an uncaught exception.
+   */
+  backoff?: number;
+  /**
+   * The timestamp indicating when the job should timeout.
+   */
+  retryUntil?: number;
+  /**
+   * The number of seconds the job can run before timing out.
+   */
+  timeout?: number;
+  /**
+   * Indicates if the job should fail if the timeout is exceeded.
+   */
+  failOnTimeout?: boolean;
+  /**
+   * Indicates if the job should be encrypted.
+   */
+  shouldBeEncrypted?: boolean;
+  /**
+   * Create a new job instance.
+   *
+   * @param  class
+   * @param method
+   * @param data
+   */
+  constructor(className: ListenerClassConstructor, method: string, data: Record<string, any>);
+  /**
+   * Handle the queued job.
+   */
+  handle(_container: Container): void;
+  /**
+   * Set the job instance of the given class if necessary.
+   *
+   * @param  job
+   * @param  instance
+   */
+  protected setJobInstanceIfNecessary(job: IJob, instance: any): {};
+  /**
+   * Call the failed method on the job instance.
+   *
+   * The event instance and the exception will be passed.
+   *
+   * @param  e
+   */
+  failed(_e: Error): void;
+  /**
+   * Unserialize the data if needed.
+   *
+   * @return void
+   */
+  protected prepareData(): void;
+  /**
+   * Get the display name for the queued job.
+   *
+   * @return string
+   */
+  displayName(): ListenerClassConstructor;
+}
+//#endregion
+export { AppEvent, AppListener, Dispatcher, EventsServiceProvider, ListenerClassConstructor, QueuedListenerCalller };

package/dist/index.js

@@ -0,0 +1,344 @@
+import { Arr, Str } from "@h3ravel/support";
+import { Container, ServiceProvider } from "@h3ravel/core";
+import { IDispatcher } from "@h3ravel/contracts";
+
+//#region src/Dispatcher.ts
+var Dispatcher = class {
+	/**
+	* The IoC container instance.
+	*/
+	container;
+	/**
+	* The registered event listeners.
+	*/
+	listeners = {};
+	/**
+	* The wildcard listeners.
+	*/
+	wildcards = {};
+	/**
+	* The cached wildcard listeners.
+	*/
+	wildcardsCache = {};
+	/**
+	* The queue resolver instance.
+	*/
+	queueResolver;
+	/**
+	* The database transaction manager resolver instance.
+	*/
+	transactionManagerResolver;
+	/**
+	* The currently deferred events.
+	*/
+	deferredEvents = {};
+	/**
+	* Indicates if events should be deferred.
+	*/
+	deferringEvents = false;
+	/**
+	* The specific events to defer (null means defer all events).
+	*/
+	eventsToDefer;
+	/**
+	* Create a new event dispatcher instance.
+	*/
+	constructor(container) {
+		this.container = container ?? new Container();
+	}
+	/**
+	* Register an event listener with the dispatcher.
+	*
+	* @param  events
+	* @param listener
+	*/
+	listen(events, listener) {
+		for (const event of Arr.wrap(events)) if (typeof event === "string" && listener) if (event.includes("*")) this.setupWildcardListen(event, listener);
+		else this.listeners[event].push(listener);
+		else if (typeof event === "function") event(listener);
+		else if (typeof listener === "function") listener();
+	}
+	/**
+	* Setup a wildcard listener callback.
+	*
+	* @param  event
+	* @param  listener
+	*/
+	setupWildcardListen(event, listener) {
+		this.wildcards[event].push(listener);
+		this.wildcardsCache = {};
+	}
+	/**
+	* Determine if a given event has listeners.
+	*
+	* @param  eventName
+	* @return bool
+	*/
+	hasListeners(eventName) {
+		return this.listeners[eventName] || this.wildcards[eventName] || this.hasWildcardListeners(eventName);
+	}
+	/**
+	* Determine if the given event has any wildcard listeners.
+	*
+	* @param  eventName
+	*/
+	hasWildcardListeners(eventName) {
+		for (const [key] of Object.entries(this.wildcards)) if (Str.is(key, eventName)) return true;
+		return false;
+	}
+	/**
+	* Register an event and payload to be fired later.
+	*
+	* @para  event
+	* @param payload
+	* @return void
+	*/
+	push(event, payload = []) {
+		this.listen(event + "_pushed", () => {
+			this.dispatch(event, payload);
+		});
+	}
+	/**
+	* Flush a set of pushed events.
+	*
+	* @param event
+	*/
+	flush(event) {
+		this.dispatch(event + "_pushed");
+	}
+	/**
+	* Resolve the subscriber instance.
+	*
+	* @param  subscriber
+	*/
+	resolveSubscriber(subscriber) {
+		if (typeof subscriber === "string") return this.container.make(subscriber);
+		return subscriber;
+	}
+	/**
+	* Fire an event until the first non-null response is returned.
+	*
+	* @param event
+	* @param  mixed  payload
+	* @return mixed
+	*/
+	until(event, payload = {}) {
+		return this.dispatch(event, payload, true);
+	}
+	/**
+	* Fire an event and call the listeners.
+	*
+	* @param event
+	* @param payload
+	* @param halt
+	*/
+	dispatch(event, _payload = [], _halt = false) {}
+	/**
+	* Remove a set of listeners from the dispatcher.
+	*
+	* @param  event
+	*/
+	forget(event) {
+		if (event.includes("*")) delete this.wildcards[event];
+		else delete this.listeners[event];
+		for (const [key] of Object.entries(this.wildcardsCache)) if (Str.is(event, key)) delete this.wildcardsCache[key];
+	}
+	/**
+	* Forget all of the pushed listeners.
+	*
+	* @return void
+	*/
+	forgetPushed() {
+		for (const [key] of Object.entries(this.listeners)) if (key.endsWith("_pushed")) this.forget(key);
+	}
+	/**
+	* Get the queue implementation from the resolver.
+	*/
+	resolveQueue() {
+		return this.queueResolver?.();
+	}
+	/**
+	* Set the queue resolver implementation.
+	*
+	* @param  callable  $resolver
+	* @return this
+	*/
+	setQueueResolver(resolver) {
+		this.queueResolver = resolver;
+		return this;
+	}
+	/**
+	* Get the database transaction manager implementation from the resolver.
+	*/
+	resolveTransactionManager() {
+		return this.transactionManagerResolver?.();
+	}
+	/**
+	* Set the database transaction manager resolver implementation.
+	*
+	* @param resolver
+	*/
+	setTransactionManagerResolver(resolver) {
+		this.transactionManagerResolver = resolver;
+		return this;
+	}
+	/**
+	* Execute the given callback while deferring events, then dispatch all deferred events.
+	*
+	* @param  callback
+	* @param  events
+	*/
+	defer(callback, events) {
+		const wasDeferring = this.deferringEvents;
+		const previousDeferredEvents = this.deferredEvents;
+		const previousEventsToDefer = this.eventsToDefer;
+		this.deferringEvents = true;
+		this.deferredEvents = {};
+		this.eventsToDefer = events;
+		try {
+			const result = callback();
+			this.deferringEvents = false;
+			for (const args of Object.entries(this.deferredEvents)) this.dispatch(...args);
+			return result;
+		} finally {
+			this.deferringEvents = wasDeferring;
+			this.deferredEvents = previousDeferredEvents;
+			this.eventsToDefer = previousEventsToDefer;
+		}
+	}
+	/**
+	* Determine if the given event should be deferred.
+	*
+	* @param  event
+	*/
+	shouldDeferEvent(event) {
+		return this.deferringEvents && (this.eventsToDefer === null || this.eventsToDefer?.includes(event));
+	}
+	/**
+	* Gets the raw, unprepared listeners.
+	*
+	* @return array
+	*/
+	getRawListeners() {
+		return this.listeners;
+	}
+};
+
+//#endregion
+//#region src/Providers/EventsServiceProvider.ts
+/**
+* Events handling.
+*/
+var EventsServiceProvider = class extends ServiceProvider {
+	static priority = 992;
+	static order = "before:RouteServiceProvider";
+	register() {
+		this.app.singleton("app.events", (app) => {
+			return new Dispatcher(app).setQueueResolver(() => {}).setTransactionManagerResolver(function() {});
+		});
+		this.app.alias([
+			["events", "app.events"],
+			[Dispatcher, "app.events"],
+			[IDispatcher, "app.events"]
+		]);
+	}
+};
+
+//#endregion
+//#region src/QueuedListenerCalller.ts
+var QueuedListenerCalller = class {
+	/**
+	* The underlying queue job instance.
+	*/
+	job;
+	/**
+	* The listener class.
+	*/
+	className;
+	/**
+	* The listener method.
+	*/
+	method;
+	/**
+	* The data to be passed to the listener.
+	*/
+	data;
+	/**
+	* The number of times the job may be attempted.
+	*/
+	tries;
+	/**
+	* The maximum number of exceptions allowed, regardless of attempts.
+	*/
+	maxExceptions;
+	/**
+	* The number of seconds to wait before retrying a job that encountered an uncaught exception.
+	*/
+	backoff;
+	/**
+	* The timestamp indicating when the job should timeout.
+	*/
+	retryUntil;
+	/**
+	* The number of seconds the job can run before timing out.
+	*/
+	timeout;
+	/**
+	* Indicates if the job should fail if the timeout is exceeded.
+	*/
+	failOnTimeout = false;
+	/**
+	* Indicates if the job should be encrypted.
+	*/
+	shouldBeEncrypted = false;
+	/**
+	* Create a new job instance.
+	*
+	* @param  class
+	* @param method
+	* @param data
+	*/
+	constructor(className, method, data) {
+		this.data = data;
+		this.className = className;
+		this.method = method;
+	}
+	/**
+	* Handle the queued job.
+	*/
+	handle(_container) {}
+	/**
+	* Set the job instance of the given class if necessary.
+	*
+	* @param  job
+	* @param  instance
+	*/
+	setJobInstanceIfNecessary(job, instance) {
+		return {};
+	}
+	/**
+	* Call the failed method on the job instance.
+	*
+	* The event instance and the exception will be passed.
+	*
+	* @param  e
+	*/
+	failed(_e) {}
+	/**
+	* Unserialize the data if needed.
+	*
+	* @return void
+	*/
+	prepareData() {}
+	/**
+	* Get the display name for the queued job.
+	*
+	* @return string
+	*/
+	displayName() {
+		return this.className;
+	}
+};
+
+//#endregion
+export { Dispatcher, EventsServiceProvider, QueuedListenerCalller };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@h3ravel/events",
+  "version": "0.1.0-alpha.1",
+  "description": "Events package for H3ravel.",
+  "h3ravel": {
+    "providers": [
+      "EventsServiceProvider"
+    ]
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./*": "./*"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://h3ravel.toneflix.net",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/h3ravel/framework.git",
+    "directory": "packages/events"
+  },
+  "keywords": [
+    "h3ravel",
+    "modern",
+    "web",
+    "H3",
+    "events",
+    "framework",
+    "nodejs",
+    "typescript",
+    "laravel"
+  ],
+  "peerDependencies": {
+    "@h3ravel/core": "^1.22.0-alpha.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "scripts": {
+    "build": "tsdown --config-loader unconfig",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "lint": "eslint . --ext .ts",
+    "test": "jest --passWithNoTests",
+    "version-patch": "pnpm version patch"
+  }
+}