@valkyrjaio/valkyrja 26.6.5 → 26.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@valkyrjaio/valkyrja",
-    "version": "26.6.5",
+    "version": "26.7.0",
     "description": "The Valkyrja Framework.",
     "keywords": [
         "framework",

package/src/Valkyrja/Application/Constant/ApplicationInfo.ts

@@ -7,8 +7,8 @@
  */
 
 export class ApplicationInfo {
-    static readonly VERSION = '26.6.5' as const;
-    static readonly VERSION_BUILD_DATE_TIME = 'August 6 2026 08:18:50 MST' as const;
+    static readonly VERSION = '26.7.0' as const;
+    static readonly VERSION_BUILD_DATE_TIME = 'August 7 2026 07:13:22 MST' as const;
     static readonly ASCII = `
                  _ _               _
      /\\   /\\__ _| | | ___   _ _ __(_) __ _

package/src/Valkyrja/Application/Provider/ApplicationComponentProvider.ts

@@ -7,6 +7,7 @@
  */
 
 import { ContainerComponentProvider } from '../../Container/Provider/ContainerComponentProvider.ts';
+import { EventComponentProvider } from '../../Event/Provider/EventComponentProvider.ts';
 
 import type { ApplicationContract } from '../Kernel/Contract/ApplicationContract.ts';
 import type { ComponentProviderContract } from './Contract/ComponentProviderContract.ts';
@@ -17,7 +18,7 @@ import type { HttpRouteProviderContract } from '../../Http/Routing/Provider/Cont
 
 export class ApplicationComponentProvider implements ComponentProviderContract {
     getComponentProviders(_app: ApplicationContract): ComponentProviderContract[] {
-        return [new ContainerComponentProvider()];
+        return [new ContainerComponentProvider(), new EventComponentProvider()];
     }
 
     getContainerProviders(_app: ApplicationContract): ServiceProviderContract[] {

package/src/Valkyrja/Container/Manager/Container.ts

@@ -7,7 +7,6 @@
  */
 
 import { ContainerData } from '../Data/ContainerData.ts';
-import { InvalidReferenceMode } from '../Enum/InvalidReferenceMode.ts';
 import { ContainerInvalidReferenceException } from '../Throwable/Exception/ContainerInvalidReferenceException.ts';
 import { ContainerInvalidPublishCallbackException } from '../Throwable/Exception/ContainerInvalidPublishCallbackException.ts';
 
@@ -96,18 +95,16 @@ export class Container implements ContainerContract {
         return id in this.instances;
     }
 
-    get<T extends object>(
-        id: string,
-        args: unknown[] = [],
-        mode: InvalidReferenceMode = InvalidReferenceMode.NEW_INSTANCE_OR_THROW_EXCEPTION,
-    ): T {
+    get<T extends object>(id: string, args: unknown[] = []): T {
         this.publishUnpublishedProvided(id);
 
         return (
             this.getSingletonWithoutChecks<T>(id) ??
             this.getServiceWithoutChecks<T>(id, args) ??
             this.getAliasedWithoutChecks<T>(id, args) ??
-            this.getFallback<T>(id, args, mode)
+            (() => {
+                throw new ContainerInvalidReferenceException(id);
+            })()
         );
     }
 
@@ -227,14 +224,6 @@ export class Container implements ContainerContract {
         return this.deferredCallback[id];
     }
 
-    protected getFallback<T extends object>(
-        id: string,
-        _args: unknown[] = [],
-        _mode: InvalidReferenceMode = InvalidReferenceMode.NEW_INSTANCE_OR_THROW_EXCEPTION,
-    ): T {
-        throw new ContainerInvalidReferenceException(id);
-    }
-
     protected publishUnpublishedProvided(id: string): void {
         if (this.isDeferred(id) && !this.isPublished(id)) {
             this.publish(id);

package/src/Valkyrja/Container/Manager/Contract/ContainerContract.ts

@@ -7,7 +7,6 @@
  */
 
 import type { ContainerData } from '../../Data/ContainerData.ts';
-import type { InvalidReferenceMode } from '../../Enum/InvalidReferenceMode.ts';
 import type { ProvidersAwareContract } from './ProvidersAwareContract.ts';
 
 export interface ContainerContract extends ProvidersAwareContract {
@@ -23,7 +22,7 @@ export interface ContainerContract extends ProvidersAwareContract {
     isSingleton(id: string): boolean;
     isSingletonBinding(id: string): boolean;
     isSingletonInstance(id: string): boolean;
-    get<T extends object>(id: string, args?: unknown[], mode?: InvalidReferenceMode): T;
+    get<T extends object>(id: string, args?: unknown[]): T;
     getAliased<T extends object>(id: string, args?: unknown[]): T;
     getService<T extends object>(id: string, args?: unknown[]): T;
     getSingleton<T extends object>(id: string): T;

package/src/Valkyrja/Event/Collection/Contract/ListenerCollectionContract.ts

@@ -0,0 +1,111 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import type { EventContract } from '../../Contract/EventContract.ts';
+import type { ListenerContract } from '../../Data/Contract/ListenerContract.ts';
+import type { EventData } from '../../Data/EventData.ts';
+
+export interface ListenerCollectionContract {
+    /**
+     * Get a data representation of the collection.
+     */
+    getData(): EventData;
+
+    /**
+     * Set data from a data object.
+     */
+    setFromData(data: EventData): void;
+
+    /**
+     * Determine if a listener is registered.
+     */
+    hasListener(listener: ListenerContract): boolean;
+
+    /**
+     * Determine if a listener is registered by its id.
+     */
+    hasListenerById(listenerId: string): boolean;
+
+    /**
+     * Add a listener.
+     */
+    addListener(listener: ListenerContract): void;
+
+    /**
+     * Remove a listener.
+     */
+    removeListener(listener: ListenerContract): void;
+
+    /**
+     * Remove a listener by id.
+     */
+    removeListenerById(listenerId: string): void;
+
+    /**
+     * Determine if listeners exist for a given event.
+     */
+    hasListenersForEvent(event: EventContract): boolean;
+
+    /**
+     * Determine if listeners exist for a given event id.
+     */
+    hasListenersForEventById(eventId: string): boolean;
+
+    /**
+     * Get all listeners for a given event, in the order that the collection
+     * recorded them.
+     */
+    getListenersForEvent(event: EventContract): ListenerContract[];
+
+    /**
+     * Get all listeners for a given event id, in the order that the collection
+     * recorded them.
+     */
+    getListenersForEventById(eventId: string): ListenerContract[];
+
+    /**
+     * Set listeners for a given event.
+     */
+    setListenersForEvent(event: EventContract, ...listeners: ListenerContract[]): void;
+
+    /**
+     * Set listeners for a given event id.
+     */
+    setListenersForEventById(eventId: string, ...listeners: ListenerContract[]): void;
+
+    /**
+     * Remove all listeners for a given event.
+     */
+    removeListenersForEvent(event: EventContract): void;
+
+    /**
+     * Remove all listeners for a given event id.
+     */
+    removeListenersForEventById(eventId: string): void;
+
+    /**
+     * Get all listeners.
+     */
+    getListeners(): ListenerContract[];
+
+    /**
+     * Get the id of every registered event that has listeners.
+     */
+    getEvents(): string[];
+
+    /**
+     * Get every registered event with its listeners.
+     */
+    getEventsWithListeners(): Record<string, ListenerContract[]>;
+}
+
+export namespace ListenerCollectionContract {
+    export function instanceOf(value: unknown): value is ListenerCollectionContract {
+        return typeof value === 'object' && value !== null && 'getListenersForEvent' in value;
+    }
+}

package/src/Valkyrja/Event/Collection/ListenerCollection.ts

@@ -0,0 +1,171 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { EventData } from '../Data/EventData.ts';
+
+import type { EventContract } from '../Contract/EventContract.ts';
+import type { ListenerContract, ListenerFactory } from '../Data/Contract/ListenerContract.ts';
+import type { ListenerCollectionContract } from './Contract/ListenerCollectionContract.ts';
+
+export class ListenerCollection implements ListenerCollectionContract {
+    // A Map, not an object, because an object reorders a key that reads as an integer.
+    protected events = new Map<string, string[]>();
+    protected listeners = new Map<string, ListenerFactory>();
+
+    getData(): EventData {
+        const events: Record<string, string[]> = {};
+
+        for (const [eventId, listenerIds] of this.events) {
+            events[eventId] = [...listenerIds];
+        }
+
+        return new EventData(events, Object.fromEntries(this.listeners));
+    }
+
+    setFromData(data: EventData): void {
+        this.events = new Map(
+            Object.entries(data.events).map(([eventId, listenerIds]): [string, string[]] => [
+                eventId,
+                [...listenerIds],
+            ]),
+        );
+        this.listeners = new Map(Object.entries(data.listeners));
+    }
+
+    hasListener(listener: ListenerContract): boolean {
+        return this.hasListenerById(listener.getName());
+    }
+
+    hasListenerById(listenerId: string): boolean {
+        return this.listeners.has(listenerId);
+    }
+
+    addListener(listener: ListenerContract): void {
+        const listenerId = listener.getName();
+        const eventId = listener.getEventId();
+
+        let listenerIds = this.events.get(eventId);
+
+        if (listenerIds === undefined) {
+            listenerIds = [];
+
+            this.events.set(eventId, listenerIds);
+        }
+
+        if (!listenerIds.includes(listenerId)) {
+            listenerIds.push(listenerId);
+        }
+
+        this.listeners.set(listenerId, (): ListenerContract => listener);
+    }
+
+    removeListener(listener: ListenerContract): void {
+        const listenerId = listener.getName();
+        const listenerIds = this.events.get(listener.getEventId());
+
+        if (listenerIds !== undefined) {
+            this.removeValue(listenerIds, listenerId);
+        }
+
+        this.listeners.delete(listenerId);
+    }
+
+    removeListenerById(listenerId: string): void {
+        for (const listenerIds of this.events.values()) {
+            this.removeValue(listenerIds, listenerId);
+        }
+
+        this.listeners.delete(listenerId);
+    }
+
+    hasListenersForEvent(event: EventContract): boolean {
+        return this.hasListenersForEventById(event.getEventId());
+    }
+
+    hasListenersForEventById(eventId: string): boolean {
+        const listenerIds = this.events.get(eventId);
+
+        return listenerIds !== undefined && listenerIds.length > 0;
+    }
+
+    getListenersForEvent(event: EventContract): ListenerContract[] {
+        return this.getListenersForEventById(event.getEventId());
+    }
+
+    getListenersForEventById(eventId: string): ListenerContract[] {
+        return this.getListenersByIds(this.events.get(eventId) ?? []);
+    }
+
+    setListenersForEvent(event: EventContract, ...listeners: ListenerContract[]): void {
+        this.setListenersForEventById(event.getEventId(), ...listeners);
+    }
+
+    setListenersForEventById(eventId: string, ...listeners: ListenerContract[]): void {
+        for (const listener of listeners) {
+            this.addListener(listener.withEventId(eventId));
+        }
+    }
+
+    removeListenersForEvent(event: EventContract): void {
+        this.removeListenersForEventById(event.getEventId());
+    }
+
+    removeListenersForEventById(eventId: string): void {
+        for (const listener of this.getListenersForEventById(eventId)) {
+            this.removeListener(listener);
+        }
+
+        this.events.delete(eventId);
+    }
+
+    getListeners(): ListenerContract[] {
+        return this.getListenersByIds(this.listeners.keys());
+    }
+
+    getEvents(): string[] {
+        return [...this.events.keys()];
+    }
+
+    getEventsWithListeners(): Record<string, ListenerContract[]> {
+        const eventsWithListeners: Record<string, ListenerContract[]> = {};
+
+        for (const eventId of this.events.keys()) {
+            eventsWithListeners[eventId] = this.getListenersForEventById(eventId);
+        }
+
+        return eventsWithListeners;
+    }
+
+    /**
+     * Build each listener that the names identify.
+     */
+    protected getListenersByIds(listenerIds: Iterable<string>): ListenerContract[] {
+        const listeners: ListenerContract[] = [];
+
+        for (const listenerId of listenerIds) {
+            const factory = this.listeners.get(listenerId);
+
+            if (factory !== undefined) {
+                listeners.push(factory());
+            }
+        }
+
+        return listeners;
+    }
+
+    /**
+     * Remove one name from an array of listener names, in place.
+     */
+    protected removeValue(listenerIds: string[], listenerId: string): void {
+        const index = listenerIds.indexOf(listenerId);
+
+        if (index !== -1) {
+            listenerIds.splice(index, 1);
+        }
+    }
+}

package/src/Valkyrja/Event/Constant/EventServiceId.ts

@@ -8,4 +8,6 @@
 
 export class EventServiceId {
     static readonly EventData = 'Valkyrja.Event.Data.EventData' as const;
+    static readonly ListenerCollectionContract = 'Valkyrja.Event.Collection.ListenerCollectionContract' as const;
+    static readonly EventDispatcherContract = 'Valkyrja.Event.Dispatcher.EventDispatcherContract' as const;
 }

package/src/Valkyrja/Event/Contract/ArgumentsCapableEventContract.ts

@@ -0,0 +1,24 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { EventContract } from './EventContract.ts';
+
+export interface ArgumentsCapableEventContract extends EventContract {
+    /**
+     * Set the arguments.
+     *
+     * @param args The arguments
+     */
+    setArguments(args: unknown[]): ArgumentsCapableEventContract;
+}
+
+export namespace ArgumentsCapableEventContract {
+    export function instanceOf(value: unknown): value is ArgumentsCapableEventContract {
+        return EventContract.instanceOf(value) && 'setArguments' in value;
+    }
+}

package/src/Valkyrja/Event/Contract/DispatchCollectableEventContract.ts

@@ -0,0 +1,29 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { EventContract } from './EventContract.ts';
+
+export interface DispatchCollectableEventContract extends EventContract {
+    /**
+     * Add a dispatch.
+     *
+     * @param dispatch The value that one listener returned
+     */
+    addDispatch(dispatch: unknown): void;
+
+    /**
+     * Get what each listener returned, in the order that the dispatcher ran them.
+     */
+    getDispatches(): unknown[];
+}
+
+export namespace DispatchCollectableEventContract {
+    export function instanceOf(value: unknown): value is DispatchCollectableEventContract {
+        return EventContract.instanceOf(value) && 'addDispatch' in value;
+    }
+}

package/src/Valkyrja/Event/Contract/EventContract.ts

@@ -0,0 +1,20 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+export interface EventContract {
+    /**
+     * Get the identifier of the event.
+     */
+    getEventId(): string;
+}
+
+export namespace EventContract {
+    export function instanceOf(value: unknown): value is EventContract {
+        return typeof value === 'object' && value !== null && 'getEventId' in value;
+    }
+}

package/src/Valkyrja/Event/Contract/StoppableEventContract.ts

@@ -0,0 +1,22 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { EventContract } from './EventContract.ts';
+
+export interface StoppableEventContract extends EventContract {
+    /**
+     * Determine if the dispatcher stops before it runs the next listener.
+     */
+    isPropagationStopped(): boolean;
+}
+
+export namespace StoppableEventContract {
+    export function instanceOf(value: unknown): value is StoppableEventContract {
+        return EventContract.instanceOf(value) && 'isPropagationStopped' in value;
+    }
+}

package/src/Valkyrja/Event/Data/Contract/ListenerContract.ts

@@ -8,13 +8,47 @@
 
 import type { ContainerContract } from '../../../Container/Manager/Contract/ContainerContract.ts';
 
+/** The arguments hold the event under the `event` key. */
+export type ListenerHandler = (container: ContainerContract, args: Record<string, unknown>) => unknown;
+
+export type ListenerFactory = () => ListenerContract;
+
 export interface ListenerContract {
+    /**
+     * Get the identifier of the event that the listener listens for.
+     */
     getEventId(): string;
+
+    /**
+     * Create a new listener with the specified event identifier.
+     *
+     * @param eventId The event identifier
+     */
     withEventId(eventId: string): ListenerContract;
+
+    /**
+     * Get the unique name that the collection files the listener under.
+     */
     getName(): string;
+
+    /**
+     * Create a new listener with the specified unique name.
+     *
+     * @param name A unique name for the listener
+     */
     withName(name: string): ListenerContract;
-    getHandler(): (container: ContainerContract, args?: unknown[]) => unknown;
-    withHandler(handler: (container: ContainerContract, args?: unknown[]) => unknown): ListenerContract;
+
+    /**
+     * Get the handler.
+     */
+    getHandler(): ListenerHandler;
+
+    /**
+     * Create a new listener with the specified handler.
+     *
+     * @param handler The handler
+     */
+    withHandler(handler: ListenerHandler): ListenerContract;
 }
 
 export namespace ListenerContract {

package/src/Valkyrja/Event/Data/EventData.ts

@@ -6,9 +6,16 @@
  * Released under the MIT License. See LICENSE.md for details.
  */
 
+import type { ListenerFactory } from './Contract/ListenerContract.ts';
+
 export class EventData {
+    /**
+     * @param events    Each event identifier with the names of its listeners, in
+     *                  the order that the collection recorded them
+     * @param listeners A factory for each listener, keyed by the listener's name
+     */
     constructor(
         public readonly events: Record<string, string[]> = {},
-        public readonly listeners: Record<string, () => object> = {},
+        public readonly listeners: Record<string, ListenerFactory> = {},
     ) {}
 }

package/src/Valkyrja/Event/Data/Listener.ts

@@ -0,0 +1,41 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import type { ListenerContract, ListenerHandler } from './Contract/ListenerContract.ts';
+
+export class Listener implements ListenerContract {
+    constructor(
+        protected readonly eventId: string,
+        protected readonly name: string,
+        protected readonly handler: ListenerHandler,
+    ) {}
+
+    getEventId(): string {
+        return this.eventId;
+    }
+
+    withEventId(eventId: string): ListenerContract {
+        return new Listener(eventId, this.name, this.handler);
+    }
+
+    getName(): string {
+        return this.name;
+    }
+
+    withName(name: string): ListenerContract {
+        return new Listener(this.eventId, name, this.handler);
+    }
+
+    getHandler(): ListenerHandler {
+        return this.handler;
+    }
+
+    withHandler(handler: ListenerHandler): ListenerContract {
+        return new Listener(this.eventId, this.name, handler);
+    }
+}

package/src/Valkyrja/Event/Dispatcher/Contract/EventDispatcherContract.ts

@@ -0,0 +1,54 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import type { EventContract } from '../../Contract/EventContract.ts';
+import type { ListenerContract } from '../../Data/Contract/ListenerContract.ts';
+
+export interface EventDispatcherContract {
+    /**
+     * Dispatch an event.
+     */
+    dispatch(event: EventContract): EventContract;
+
+    /**
+     * Dispatch an event if it has listeners.
+     */
+    dispatchIfHasListeners(event: EventContract): EventContract;
+
+    /**
+     * Build an event from the container and dispatch it.
+     *
+     * @param eventId The binding key of the event
+     * @param args    The arguments to pass to the event
+     */
+    dispatchById(eventId: string, args?: unknown[]): EventContract;
+
+    /**
+     * Build an event from the container and dispatch it if it has listeners.
+     *
+     * @param eventId The binding key of the event
+     * @param args    The arguments to pass to the event
+     */
+    dispatchByIdIfHasListeners(eventId: string, args?: unknown[]): EventContract;
+
+    /**
+     * Dispatch a set of listeners.
+     */
+    dispatchListeners(event: EventContract, ...listeners: ListenerContract[]): EventContract;
+
+    /**
+     * Dispatch a listener.
+     */
+    dispatchListener(event: EventContract, listener: ListenerContract): EventContract;
+}
+
+export namespace EventDispatcherContract {
+    export function instanceOf(value: unknown): value is EventDispatcherContract {
+        return typeof value === 'object' && value !== null && 'dispatchListeners' in value;
+    }
+}

package/src/Valkyrja/Event/Dispatcher/EventDispatcher.ts

@@ -0,0 +1,93 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { Container } from '../../Container/Manager/Container.ts';
+import { ArgumentsCapableEventContract } from '../Contract/ArgumentsCapableEventContract.ts';
+import { DispatchCollectableEventContract } from '../Contract/DispatchCollectableEventContract.ts';
+import { EventContract } from '../Contract/EventContract.ts';
+import { StoppableEventContract } from '../Contract/StoppableEventContract.ts';
+import { ListenerCollection } from '../Collection/ListenerCollection.ts';
+import { EventInvalidEventException } from '../Throwable/Exception/EventInvalidEventException.ts';
+
+import type { ContainerContract } from '../../Container/Manager/Contract/ContainerContract.ts';
+import type { ListenerCollectionContract } from '../Collection/Contract/ListenerCollectionContract.ts';
+import type { ListenerContract } from '../Data/Contract/ListenerContract.ts';
+import type { EventDispatcherContract } from './Contract/EventDispatcherContract.ts';
+
+export class EventDispatcher implements EventDispatcherContract {
+    constructor(
+        protected readonly collection: ListenerCollectionContract = new ListenerCollection(),
+        protected readonly container: ContainerContract = new Container(),
+    ) {}
+
+    dispatch(event: EventContract): EventContract {
+        return this.dispatchListeners(event, ...this.collection.getListenersForEvent(event));
+    }
+
+    dispatchIfHasListeners(event: EventContract): EventContract {
+        if (this.collection.hasListenersForEvent(event)) {
+            return this.dispatch(event);
+        }
+
+        return event;
+    }
+
+    dispatchById(eventId: string, args: unknown[] = []): EventContract {
+        return this.dispatch(this.getEventFromId(eventId, args));
+    }
+
+    dispatchByIdIfHasListeners(eventId: string, args: unknown[] = []): EventContract {
+        if (this.collection.hasListenersForEventById(eventId)) {
+            return this.dispatchById(eventId, args);
+        }
+
+        return this.getEventFromId(eventId, args);
+    }
+
+    dispatchListeners(event: EventContract, ...listeners: ListenerContract[]): EventContract {
+        let dispatched = event;
+
+        for (const listener of listeners) {
+            dispatched = this.dispatchListener(dispatched, listener);
+
+            if (StoppableEventContract.instanceOf(dispatched) && dispatched.isPropagationStopped()) {
+                return dispatched;
+            }
+        }
+
+        return dispatched;
+    }
+
+    dispatchListener(event: EventContract, listener: ListenerContract): EventContract {
+        const handler = listener.getHandler();
+        const dispatch = handler(this.container, { event });
+
+        if (DispatchCollectableEventContract.instanceOf(event)) {
+            event.addDispatch(dispatch);
+        }
+
+        return event;
+    }
+
+    /**
+     * Build the event that the binding key names.
+     */
+    protected getEventFromId(eventId: string, args: unknown[]): EventContract {
+        const resolved: unknown = this.container.get(eventId, args);
+
+        if (!EventContract.instanceOf(resolved)) {
+            throw new EventInvalidEventException(eventId);
+        }
+
+        if (ArgumentsCapableEventContract.instanceOf(resolved)) {
+            return resolved.setArguments(args);
+        }
+
+        return resolved;
+    }
+}

package/src/Valkyrja/Event/Provider/EventComponentProvider.ts

@@ -0,0 +1,38 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { EventServiceProvider } from './EventServiceProvider.ts';
+
+import type { ApplicationContract } from '../../Application/Kernel/Contract/ApplicationContract.ts';
+import type { ComponentProviderContract } from '../../Application/Provider/Contract/ComponentProviderContract.ts';
+import type { ServiceProviderContract } from '../../Container/Provider/Contract/ServiceProviderContract.ts';
+import type { ListenerProviderContract } from './Contract/ListenerProviderContract.ts';
+import type { CliRouteProviderContract } from '../../Cli/Routing/Provider/Contract/CliRouteProviderContract.ts';
+import type { HttpRouteProviderContract } from '../../Http/Routing/Provider/Contract/HttpRouteProviderContract.ts';
+
+export class EventComponentProvider implements ComponentProviderContract {
+    getComponentProviders(_app: ApplicationContract): ComponentProviderContract[] {
+        return [];
+    }
+
+    getContainerProviders(_app: ApplicationContract): ServiceProviderContract[] {
+        return [new EventServiceProvider()];
+    }
+
+    getEventProviders(_app: ApplicationContract): ListenerProviderContract[] {
+        return [];
+    }
+
+    getCliProviders(_app: ApplicationContract): CliRouteProviderContract[] {
+        return [];
+    }
+
+    getHttpProviders(_app: ApplicationContract): HttpRouteProviderContract[] {
+        return [];
+    }
+}

package/src/Valkyrja/Event/Provider/EventServiceProvider.ts

@@ -0,0 +1,69 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { ApplicationServiceId } from '../../Application/Constant/ApplicationServiceId.ts';
+import { ListenerCollection } from '../Collection/ListenerCollection.ts';
+import { EventServiceId } from '../Constant/EventServiceId.ts';
+import { EventDispatcher } from '../Dispatcher/EventDispatcher.ts';
+
+import type { ApplicationContract } from '../../Application/Kernel/Contract/ApplicationContract.ts';
+import type { ContainerContract } from '../../Container/Manager/Contract/ContainerContract.ts';
+import type { ServiceProviderContract } from '../../Container/Provider/Contract/ServiceProviderContract.ts';
+import type { ListenerCollectionContract } from '../Collection/Contract/ListenerCollectionContract.ts';
+import type { EventData } from '../Data/EventData.ts';
+
+export class EventServiceProvider implements ServiceProviderContract {
+    publishers(): Record<string, (container: ContainerContract) => void> {
+        return {
+            [EventServiceId.EventDispatcherContract]: EventServiceProvider.publishDispatcher,
+            [EventServiceId.ListenerCollectionContract]: EventServiceProvider.publishListenerCollection,
+            [EventServiceId.EventData]: EventServiceProvider.publishData,
+        };
+    }
+
+    static publishDispatcher(this: void, container: ContainerContract): void {
+        container.setSingleton(
+            EventServiceId.EventDispatcherContract,
+            new EventDispatcher(
+                container.getSingleton<ListenerCollectionContract>(EventServiceId.ListenerCollectionContract),
+                container,
+            ),
+        );
+    }
+
+    static publishListenerCollection(this: void, container: ContainerContract): void {
+        const collection = new ListenerCollection();
+
+        container.setSingleton(EventServiceId.ListenerCollectionContract, collection);
+
+        const app = container.getSingleton<ApplicationContract>(ApplicationServiceId.ApplicationContract);
+
+        if (app.getDebugMode()) {
+            EventServiceProvider.publishData(container);
+
+            return;
+        }
+
+        collection.setFromData(container.getSingleton<EventData>(EventServiceId.EventData));
+    }
+
+    static publishData(this: void, container: ContainerContract): void {
+        const collection = container.getSingleton<ListenerCollectionContract>(
+            EventServiceId.ListenerCollectionContract,
+        );
+        const app = container.getSingleton<ApplicationContract>(ApplicationServiceId.ApplicationContract);
+
+        for (const provider of app.getEventProviders()) {
+            for (const listener of provider.getListeners()) {
+                collection.addListener(listener);
+            }
+        }
+
+        container.setSingleton(EventServiceId.EventData, collection.getData());
+    }
+}

package/src/Valkyrja/{Container/Enum/InvalidReferenceMode.ts → Event/Throwable/Contract/EventThrowable.ts}

@@ -6,7 +6,6 @@
  * Released under the MIT License. See LICENSE.md for details.
  */
 
-export enum InvalidReferenceMode {
-    NEW_INSTANCE_OR_THROW_EXCEPTION,
-    THROW_EXCEPTION,
-}
+import { type ValkyrjaThrowable } from '../../../Throwable/Contract/ValkyrjaThrowable.ts';
+
+export type EventThrowable = ValkyrjaThrowable;

package/src/Valkyrja/Event/Throwable/Exception/Abstract/EventInvalidArgumentException.ts

@@ -0,0 +1,15 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { ValkyrjaInvalidArgumentException } from '../../../../Throwable/Exception/Abstract/ValkyrjaInvalidArgumentException.ts';
+
+import { type EventThrowable } from '../../Contract/EventThrowable.ts';
+
+export abstract class EventInvalidArgumentException
+    extends ValkyrjaInvalidArgumentException
+    implements EventThrowable {}

package/src/Valkyrja/Event/Throwable/Exception/Abstract/EventRuntimeException.ts

@@ -0,0 +1,13 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { ValkyrjaRuntimeException } from '../../../../Throwable/Exception/Abstract/ValkyrjaRuntimeException.ts';
+
+import { type EventThrowable } from '../../Contract/EventThrowable.ts';
+
+export abstract class EventRuntimeException extends ValkyrjaRuntimeException implements EventThrowable {}

package/src/Valkyrja/Event/Throwable/Exception/EventInvalidEventException.ts

@@ -0,0 +1,19 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { EventInvalidArgumentException } from './Abstract/EventInvalidArgumentException.ts';
+
+export class EventInvalidEventException extends EventInvalidArgumentException {
+    constructor(
+        public readonly id: string,
+        options?: ErrorOptions,
+    ) {
+        super(`Service with \`${id}\` is not an event`, options);
+        this.name = 'EventInvalidEventException';
+    }
+}