@orchestr-sh/orchestr 1.6.1 → 1.7.1

package/dist/Events/Decorators/HandlesEvents.d.ts

@@ -0,0 +1,83 @@
+import 'reflect-metadata';
+/**
+ * HandlesEvents Decorator
+ *
+ * Decorator to explicitly specify which events a listener handles.
+ * This is particularly useful for:
+ * - Union types (TypeScript can't reflect union type information at runtime)
+ * - Multiple events handled by a single listener
+ * - Clarifying listener behavior
+ *
+ * The decorator stores the event types in metadata that can be read by
+ * the EventDiscovery system during listener scanning.
+ *
+ * @param events Array of event class constructors this listener handles
+ * @returns Class decorator function
+ *
+ * @example
+ * ```typescript
+ * import { HandlesEvents } from '@orchestr/Events/Decorators/HandlesEvents'
+ * import { UserRegistered } from '../Events/UserRegistered'
+ * import { UserUpdated } from '../Events/UserUpdated'
+ *
+ * // Single event
+ * @HandlesEvents([UserRegistered])
+ * class SendWelcomeEmail {
+ *   handle(event: UserRegistered) {
+ *     // Send welcome email
+ *   }
+ * }
+ *
+ * // Multiple events (union type)
+ * @HandlesEvents([UserRegistered, UserUpdated])
+ * class UserNotificationListener {
+ *   handle(event: UserRegistered | UserUpdated) {
+ *     if (event instanceof UserRegistered) {
+ *       // Handle registration
+ *     } else {
+ *       // Handle update
+ *     }
+ *   }
+ * }
+ *
+ * // With ShouldQueue
+ * @HandlesEvents([OrderPlaced])
+ * class ProcessOrderListener implements ShouldQueue {
+ *   public queue = 'orders'
+ *
+ *   async handle(event: OrderPlaced) {
+ *     // Process order
+ *   }
+ * }
+ * ```
+ */
+export declare function HandlesEvents(events: Function[]): ClassDecorator;
+/**
+ * Type guard to check if a class has the HandlesEvents decorator
+ *
+ * @param target Class to check
+ * @returns True if class has HandlesEvents metadata
+ *
+ * @example
+ * ```typescript
+ * if (hasHandlesEventsMetadata(MyListener)) {
+ *   const events = getHandledEvents(MyListener)
+ *   console.log('Listener handles:', events)
+ * }
+ * ```
+ */
+export declare function hasHandlesEventsMetadata(target: any): boolean;
+/**
+ * Get the event types from a listener class decorated with @HandlesEvents
+ *
+ * @param target Listener class constructor
+ * @returns Array of event class constructors, or empty array if not decorated
+ *
+ * @example
+ * ```typescript
+ * const events = getHandledEvents(SendWelcomeEmail)
+ * // Returns: [UserRegistered]
+ * ```
+ */
+export declare function getHandledEvents(target: any): Function[];
+//# sourceMappingURL=HandlesEvents.d.ts.map

package/dist/Events/Decorators/HandlesEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HandlesEvents.d.ts","sourceRoot":"","sources":["../../../src/Events/Decorators/HandlesEvents.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,cAAc,CAQhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAK7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,GAAG,GAAG,QAAQ,EAAE,CAMxD"}

package/dist/Events/Decorators/HandlesEvents.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandlesEvents = HandlesEvents;
+exports.hasHandlesEventsMetadata = hasHandlesEventsMetadata;
+exports.getHandledEvents = getHandledEvents;
+require("reflect-metadata");
+/**
+ * HandlesEvents Decorator
+ *
+ * Decorator to explicitly specify which events a listener handles.
+ * This is particularly useful for:
+ * - Union types (TypeScript can't reflect union type information at runtime)
+ * - Multiple events handled by a single listener
+ * - Clarifying listener behavior
+ *
+ * The decorator stores the event types in metadata that can be read by
+ * the EventDiscovery system during listener scanning.
+ *
+ * @param events Array of event class constructors this listener handles
+ * @returns Class decorator function
+ *
+ * @example
+ * ```typescript
+ * import { HandlesEvents } from '@orchestr/Events/Decorators/HandlesEvents'
+ * import { UserRegistered } from '../Events/UserRegistered'
+ * import { UserUpdated } from '../Events/UserUpdated'
+ *
+ * // Single event
+ * @HandlesEvents([UserRegistered])
+ * class SendWelcomeEmail {
+ *   handle(event: UserRegistered) {
+ *     // Send welcome email
+ *   }
+ * }
+ *
+ * // Multiple events (union type)
+ * @HandlesEvents([UserRegistered, UserUpdated])
+ * class UserNotificationListener {
+ *   handle(event: UserRegistered | UserUpdated) {
+ *     if (event instanceof UserRegistered) {
+ *       // Handle registration
+ *     } else {
+ *       // Handle update
+ *     }
+ *   }
+ * }
+ *
+ * // With ShouldQueue
+ * @HandlesEvents([OrderPlaced])
+ * class ProcessOrderListener implements ShouldQueue {
+ *   public queue = 'orders'
+ *
+ *   async handle(event: OrderPlaced) {
+ *     // Process order
+ *   }
+ * }
+ * ```
+ */
+function HandlesEvents(events) {
+    return function (target) {
+        // Store event types in metadata
+        // This metadata is read by EventDiscovery.extractEventTypes()
+        Reflect.defineMetadata('event:types', events, target);
+        return target;
+    };
+}
+/**
+ * Type guard to check if a class has the HandlesEvents decorator
+ *
+ * @param target Class to check
+ * @returns True if class has HandlesEvents metadata
+ *
+ * @example
+ * ```typescript
+ * if (hasHandlesEventsMetadata(MyListener)) {
+ *   const events = getHandledEvents(MyListener)
+ *   console.log('Listener handles:', events)
+ * }
+ * ```
+ */
+function hasHandlesEventsMetadata(target) {
+    if (typeof target !== 'function')
+        return false;
+    const metadata = Reflect.getMetadata('event:types', target);
+    return metadata !== undefined && Array.isArray(metadata);
+}
+/**
+ * Get the event types from a listener class decorated with @HandlesEvents
+ *
+ * @param target Listener class constructor
+ * @returns Array of event class constructors, or empty array if not decorated
+ *
+ * @example
+ * ```typescript
+ * const events = getHandledEvents(SendWelcomeEmail)
+ * // Returns: [UserRegistered]
+ * ```
+ */
+function getHandledEvents(target) {
+    if (!hasHandlesEventsMetadata(target)) {
+        return [];
+    }
+    return Reflect.getMetadata('event:types', target) || [];
+}
+//# sourceMappingURL=HandlesEvents.js.map

package/dist/Events/Decorators/HandlesEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HandlesEvents.js","sourceRoot":"","sources":["../../../src/Events/Decorators/HandlesEvents.ts"],"names":[],"mappings":";;AAsDA,sCAQC;AAgBD,4DAKC;AAcD,4CAMC;AAvGD,4BAA0B;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,SAAgB,aAAa,CAAC,MAAkB;IAC9C,OAAO,UAAU,MAAW;QAC1B,gCAAgC;QAChC,8DAA8D;QAC9D,OAAO,CAAC,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAEtD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,wBAAwB,CAAC,MAAW;IAClD,IAAI,OAAO,MAAM,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAE/C,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAC5D,OAAO,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,gBAAgB,CAAC,MAAW;IAC1C,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,OAAO,CAAC,WAAW,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;AAC1D,CAAC"}

package/dist/Events/Dispatcher.d.ts

@@ -0,0 +1,201 @@
+import type { Container } from '../Container/Container';
+import type { DispatcherContract } from './Contracts/Dispatcher';
+import type { Event } from './Event';
+import type { EventListener, EventSubscriber } from './types';
+/**
+ * Event Dispatcher
+ *
+ * The core event dispatcher implementation. Manages event listeners,
+ * handles wildcard patterns, and dispatches events to registered listeners.
+ *
+ * @example
+ * ```typescript
+ * const dispatcher = new Dispatcher(container);
+ *
+ * // Register listeners
+ * dispatcher.listen('user.registered', SendWelcomeEmail);
+ * dispatcher.listen('user.*', LogUserActivity);
+ *
+ * // Dispatch events
+ * dispatcher.dispatch(new UserRegistered(user));
+ * ```
+ */
+export declare class Dispatcher implements DispatcherContract {
+    protected container: Container;
+    /**
+     * Registered event listeners (direct event name matches)
+     */
+    protected listeners: Map<string, EventListener[]>;
+    /**
+     * Wildcard event listeners (patterns like 'user.*')
+     */
+    protected wildcards: Map<string, EventListener[]>;
+    /**
+     * Queued events waiting to be flushed
+     */
+    protected queuedEvents: Map<string, Array<{
+        payload: any[];
+    }>>;
+    /**
+     * Create a new event dispatcher
+     *
+     * @param container - The service container for resolving listeners
+     */
+    constructor(container: Container);
+    /**
+     * Register an event listener
+     *
+     * Supports single events, multiple events, and wildcard patterns
+     *
+     * @param events - Event name(s) to listen for
+     * @param listener - Listener to invoke when event is dispatched
+     */
+    listen(events: string | string[], listener: EventListener): void;
+    /**
+     * Check if an event has any listeners
+     *
+     * Checks both direct listeners and wildcard matches
+     *
+     * @param eventName - The event name to check
+     * @returns True if the event has listeners
+     */
+    hasListeners(eventName: string): boolean;
+    /**
+     * Register an event subscriber
+     *
+     * Subscribers can register multiple event listeners at once
+     *
+     * @param subscriber - The subscriber instance
+     */
+    subscribe(subscriber: EventSubscriber): void;
+    /**
+     * Dispatch an event to all listeners
+     *
+     * @param event - Event name or instance
+     * @param payload - Additional arguments to pass to listeners
+     * @param halt - Stop dispatching if a listener returns false
+     * @returns Array of results from listeners
+     */
+    dispatch(event: string | Event, payload?: any[], halt?: boolean): any[];
+    /**
+     * Dispatch an event until a listener returns a non-null response
+     *
+     * @param event - Event name or instance
+     * @param payload - Additional arguments to pass to listeners
+     * @returns The first non-null response from a listener
+     */
+    until(event: string | Event, payload?: any[]): any;
+    /**
+     * Queue an event for later dispatch
+     *
+     * @param event - Event name
+     * @param payload - Event payload
+     */
+    push(event: string, payload?: any[]): void;
+    /**
+     * Flush (dispatch) all queued events for a specific event name
+     *
+     * @param event - Event name to flush
+     */
+    flush(event: string): void;
+    /**
+     * Remove all listeners for an event
+     *
+     * @param event - Event name
+     */
+    forget(event: string): void;
+    /**
+     * Clear all queued events
+     */
+    forgetPushed(): void;
+    /**
+     * Get raw listener mappings
+     *
+     * @returns Map of event names to their listeners
+     */
+    getRawListeners(): Map<string, EventListener[]>;
+    /**
+     * Get all listeners for an event (direct + wildcard matches)
+     *
+     * @param eventName - The event name
+     * @returns Array of listeners
+     */
+    protected getListeners(eventName: string): EventListener[];
+    /**
+     * Setup a wildcard listener
+     *
+     * @param event - Wildcard pattern (e.g., 'user.*')
+     * @param listener - Listener to invoke
+     */
+    protected setupWildcardListen(event: string, listener: EventListener): void;
+    /**
+     * Get all wildcard listeners matching an event name
+     *
+     * @param eventName - The event name to match
+     * @returns Array of matching listeners
+     */
+    protected getWildcardListeners(eventName: string): EventListener[];
+    /**
+     * Check if an event name matches a wildcard pattern
+     *
+     * Supports patterns like:
+     * - 'event.*' - Matches 'event.created', 'event.updated', etc.
+     * - 'event.*.action' - Matches 'event.user.action', 'event.post.action', etc.
+     * - '*' - Matches everything
+     *
+     * @param pattern - Wildcard pattern
+     * @param eventName - Event name to test
+     * @returns True if the pattern matches
+     */
+    protected wildcardMatch(pattern: string, eventName: string): boolean;
+    /**
+     * Parse event and payload from dispatch arguments
+     *
+     * @param event - Event name or instance
+     * @param payload - Event payload
+     * @returns Tuple of [eventName, eventInstance]
+     */
+    protected parseEventAndPayload(event: string | Event, payload: any[]): [string, Event | null];
+    /**
+     * Call a listener with the event and payload
+     *
+     * Handles different listener types (closure, class instance, string reference)
+     *
+     * @param listener - The listener to call
+     * @param event - Event name or instance
+     * @param payload - Additional payload arguments
+     * @returns The result from the listener
+     */
+    protected callListener(listener: EventListener, event: string | Event, payload: any[]): any;
+    /**
+     * Create a callable function from a listener
+     *
+     * Resolves string listeners from container and wraps class instances
+     *
+     * @param listener - The listener to convert
+     * @param wildcard - Whether this is for a wildcard listener
+     * @returns Callable function
+     */
+    protected makeListener(listener: EventListener, wildcard?: boolean): Function;
+    /**
+     * Create a listener from a class string reference
+     *
+     * Resolves the class from the container and calls its handle method
+     *
+     * @param listener - Class name/path to resolve
+     * @param wildcard - Whether this is for a wildcard listener
+     * @returns Callable function
+     */
+    protected createClassListener(listener: string, wildcard?: boolean): Function;
+    /**
+     * Check if an event should broadcast
+     *
+     * This is a placeholder for future broadcasting support
+     *
+     * @param event - The event instance
+     * @param payload - The event payload
+     * @returns True if should broadcast
+     */
+    protected shouldBroadcast(event: Event, payload: any[]): boolean;
+}
+//# sourceMappingURL=Dispatcher.d.ts.map

package/dist/Events/Dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dispatcher.d.ts","sourceRoot":"","sources":["../../src/Events/Dispatcher.ts"],"names":[],"mappings":"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"}