@jadermme/orus-core/dist/events/emitter.d.ts

ORUS Core Framework - Universal framework for 6 Pillars assessment, domain-agnostic

/**
 * ORUS Core - Event Emitter
 *
 * Simple, type-safe event emitter for ORUS Core events.
 * Enables decoupled communication between components.
 *
 * @remarks
 * This is a lightweight implementation focused on:
 * - Type safety (full TypeScript support)
 * - Simplicity (easy to understand and debug)
 * - Performance (minimal overhead)
 * - Memory safety (automatic cleanup on error)
 */
import type { OrusEvent, OrusEventType, OrusEventHandler } from '../types/events.js';
/**
 * ORUS Event Emitter
 *
 * @remarks
 * Simple pub/sub event system for ORUS Core.
 * Supports typed events, one-time listeners, and wildcard listeners.
 *
 * @example
 * ```typescript
 * const emitter = new OrusEventEmitter();
 *
 * // Subscribe to events
 * emitter.on(OrusEventType.PILLAR_SCORE_UPDATED, (event) => {
 *   console.log('Score updated:', event.payload);
 * });
 *
 * // Emit event
 * emitter.emit({
 *   type: OrusEventType.PILLAR_SCORE_UPDATED,
 *   timestamp: new Date(),
 *   payload: { pillarId: 'PILLAR_1', newScore: 7.5 }
 * });
 * ```
 */
export declare class OrusEventEmitter {
    /**
     * Event listeners map
     */
    private listeners;
    /**
     * Maximum listeners per event type (prevents memory leaks)
     */
    private maxListeners;
    /**
     * Creates a new event emitter
     *
     * @param maxListeners - Maximum listeners per event (default: 10)
     */
    constructor(maxListeners?: number);
    /**
     * Subscribes to an event
     *
     * @param type - Event type to listen for
     * @param handler - Event handler function
     * @returns Unsubscribe function
     *
     * @remarks
     * - Handler is called each time the event is emitted
     * - Returns a function to unsubscribe
     * - Throws if max listeners exceeded
     *
     * @example
     * ```typescript
     * const unsubscribe = emitter.on(
     *   OrusEventType.PILLAR_SCORE_UPDATED,
     *   (event) => console.log(event.payload)
     * );
     *
     * // Later: stop listening
     * unsubscribe();
     * ```
     */
    on<T = any>(type: OrusEventType | '*', handler: OrusEventHandler<T>): () => void;
    /**
     * Subscribes to an event (one-time only)
     *
     * @param type - Event type to listen for
     * @param handler - Event handler function
     * @returns Unsubscribe function
     *
     * @remarks
     * - Handler is called once and then automatically removed
     * - Useful for one-time reactions
     *
     * @example
     * ```typescript
     * emitter.once(OrusEventType.ASSESSMENT_COMPLETED, (event) => {
     *   console.log('Assessment completed!', event.payload);
     *   // This handler will only run once
     * });
     * ```
     */
    once<T = any>(type: OrusEventType | '*', handler: OrusEventHandler<T>): () => void;
    /**
     * Unsubscribes from an event
     *
     * @param type - Event type to stop listening for
     * @param handler - Handler to remove
     *
     * @remarks
     * - Removes the specific handler for the given event type
     * - No-op if handler is not found
     *
     * @example
     * ```typescript
     * const handler = (event) => console.log(event);
     * emitter.on(OrusEventType.PILLAR_SCORE_UPDATED, handler);
     *
     * // Later: remove listener
     * emitter.off(OrusEventType.PILLAR_SCORE_UPDATED, handler);
     * ```
     */
    off<T = any>(type: OrusEventType | '*', handler: OrusEventHandler<T>): void;
    /**
     * Emits an event to all subscribers
     *
     * @param event - Event to emit
     * @returns Promise that resolves when all handlers complete
     *
     * @remarks
     * - Calls all registered handlers for this event type
     * - Also calls wildcard ('*') handlers
     * - Handlers are called in registration order
     * - One-time handlers are automatically removed after execution
     * - Errors in handlers are caught and logged (don't stop other handlers)
     * - Returns promise for async handlers
     *
     * @example
     * ```typescript
     * await emitter.emit({
     *   type: OrusEventType.PILLAR_SCORE_UPDATED,
     *   timestamp: new Date(),
     *   payload: {
     *     pillarId: 'PILLAR_1',
     *     oldScore: 5.0,
     *     newScore: 7.5
     *   }
     * });
     * ```
     */
    emit<T = any>(event: OrusEvent<T>): Promise<void>;
    /**
     * Removes all listeners for a specific event type
     *
     * @param type - Event type to clear (optional, clears all if not provided)
     *
     * @remarks
     * - Removes all listeners for the given type
     * - If no type provided, removes ALL listeners
     *
     * @example
     * ```typescript
     * // Remove all listeners for one event type
     * emitter.removeAllListeners(OrusEventType.PILLAR_SCORE_UPDATED);
     *
     * // Remove ALL listeners
     * emitter.removeAllListeners();
     * ```
     */
    removeAllListeners(type?: OrusEventType | '*'): void;
    /**
     * Gets count of listeners for an event type
     *
     * @param type - Event type to count
     * @returns Number of listeners
     *
     * @example
     * ```typescript
     * const count = emitter.listenerCount(OrusEventType.PILLAR_SCORE_UPDATED);
     * console.log(`${count} listeners registered`);
     * ```
     */
    listenerCount(type: OrusEventType | '*'): number;
    /**
     * Gets all event types with active listeners
     *
     * @returns Array of event types
     *
     * @example
     * ```typescript
     * const types = emitter.eventTypes();
     * console.log('Active event types:', types);
     * ```
     */
    eventTypes(): Array<OrusEventType | '*'>;
    /**
     * Sets maximum listeners per event type
     *
     * @param max - Maximum listeners (must be > 0)
     *
     * @remarks
     * - Prevents memory leaks from unbounded listener registration
     * - Default is 10
     * - Set to 0 for unlimited (not recommended)
     */
    setMaxListeners(max: number): void;
    /**
     * Gets maximum listeners setting
     *
     * @returns Current max listeners value
     */
    getMaxListeners(): number;
}
/**
 * Creates a new event emitter instance
 *
 * @param maxListeners - Maximum listeners per event (default: 10)
 * @returns New event emitter
 *
 * @example
 * ```typescript
 * const emitter = createEventEmitter(20);
 * ```
 */
export declare function createEventEmitter(maxListeners?: number): OrusEventEmitter;
//# sourceMappingURL=emitter.d.ts.map