@spfn/core/dist/events/index.d.ts

SPFN Framework Core - File-based routing, transactions, repository pattern

/**
 * Event handler function type
 */
type EventHandler<T = any> = (data: T) => Promise<void> | void;
/**
 * EventEmitter interface
 *
 * All event emitter adapters must implement this interface
 */
interface EventEmitter {
    /**
     * Subscribe to an event
     *
     * @param event - Event name
     * @param handler - Event handler function
     */
    on(event: string, handler: EventHandler): void;
    /**
     * Emit an event
     *
     * @param event - Event name
     * @param data - Event data
     */
    emit(event: string, data?: any): Promise<void>;
    /**
     * Unsubscribe from an event
     *
     * @param event - Event name
     */
    off(event: string): void;
    /**
     * Clear all event subscriptions
     */
    clear(): void;
}

/**
 * Event Emitter
 *
 * Adapter-based event emitter for decoupled communication between packages.
 *
 * Default adapter: InMemoryEventEmitter (single-instance)
 *
 * @example
 * ```typescript
 * // Subscribe to events
 * import { on } from '@spfn/core/events';
 *
 * on('user:created', async (data) => {
 *   console.log('User created:', data.email);
 * });
 *
 * // Emit events
 * import { emit } from '@spfn/core/events';
 *
 * await emit('user:created', {
 *   userId: '123',
 *   email: 'user@example.com'
 * });
 *
 * // Switch to Redis adapter (multi-instance)
 * import { setEventEmitter } from '@spfn/core/events';
 * import { RedisEventEmitter } from '@spfn/core/events/adapters';
 *
 * setEventEmitter(new RedisEventEmitter({
 *   host: 'localhost',
 *   port: 6379
 * }));
 * ```
 */

/**
 * Set the event emitter adapter
 *
 * @param adapter - EventEmitter adapter implementation
 *
 * @example
 * ```typescript
 * import { setEventEmitter } from '@spfn/core/events';
 * import { InMemoryEventEmitter } from '@spfn/core/events/adapters';
 *
 * setEventEmitter(new InMemoryEventEmitter());
 * ```
 */
declare function setEventEmitter(adapter: EventEmitter): void;
/**
 * Get the current event emitter adapter
 *
 * @returns Current EventEmitter instance
 */
declare function getEventEmitter(): EventEmitter;
/**
 * Subscribe to an event
 *
 * @param event - Event name
 * @param handler - Event handler function
 *
 * @example
 * ```typescript
 * on('user:created', async (data) => {
 *   console.log('User created:', data.email);
 * });
 * ```
 */
declare function on(event: string, handler: EventHandler): void;
/**
 * Emit an event
 *
 * @param event - Event name
 * @param data - Event data
 *
 * @example
 * ```typescript
 * await emit('user:created', {
 *   userId: '123',
 *   email: 'user@example.com'
 * });
 * ```
 */
declare function emit(event: string, data?: any): Promise<void>;
/**
 * Unsubscribe from an event
 *
 * @param event - Event name
 *
 * @example
 * ```typescript
 * off('user:created');
 * ```
 */
declare function off(event: string): void;
/**
 * Clear all event subscriptions
 *
 * Useful for testing or cleanup
 *
 * @example
 * ```typescript
 * // In tests
 * beforeEach(() => {
 *   clear();
 * });
 * ```
 */
declare function clear(): void;

/**
 * In-Memory Event Emitter
 *
 * Simple in-process event emitter for single-instance deployments.
 * Events are not shared across multiple server instances.
 *
 * Use this adapter for:
 * - Development
 * - Single-instance production deployments
 * - When you don't need distributed events
 *
 * @example
 * ```typescript
 * import { setEventEmitter } from '@spfn/core/events';
 * import { InMemoryEventEmitter } from '@spfn/core/events/adapters';
 *
 * setEventEmitter(new InMemoryEventEmitter());
 * ```
 */

declare class InMemoryEventEmitter implements EventEmitter {
    private listeners;
    on(event: string, handler: EventHandler): void;
    emit(event: string, data?: any): Promise<void>;
    off(event: string): void;
    clear(): void;
    /**
     * Get list of registered events (for debugging)
     */
    getEvents(): string[];
    /**
     * Get number of handlers for an event (for debugging)
     */
    getHandlerCount(event: string): number;
}

export { type EventEmitter, type EventHandler, InMemoryEventEmitter, clear, emit, getEventEmitter, off, on, setEventEmitter };