@scarlett-player/core 0.1.1 → 0.1.2

package/dist/error-handler.d.ts

@@ -0,0 +1,229 @@
+/**
+ * ErrorHandler - Centralized error handling for Scarlett Player.
+ *
+ * Provides error classification, logging, history tracking, and event emission
+ * for all player errors.
+ *
+ * Target size: ~0.4-0.6KB
+ */
+import type { EventBus } from './events/event-bus';
+import type { Logger } from './logger';
+/**
+ * Player error codes.
+ */
+export declare enum ErrorCode {
+    SOURCE_NOT_SUPPORTED = "SOURCE_NOT_SUPPORTED",
+    SOURCE_LOAD_FAILED = "SOURCE_LOAD_FAILED",
+    PROVIDER_NOT_FOUND = "PROVIDER_NOT_FOUND",
+    PROVIDER_SETUP_FAILED = "PROVIDER_SETUP_FAILED",
+    PLUGIN_SETUP_FAILED = "PLUGIN_SETUP_FAILED",
+    PLUGIN_NOT_FOUND = "PLUGIN_NOT_FOUND",
+    PLAYBACK_FAILED = "PLAYBACK_FAILED",
+    MEDIA_DECODE_ERROR = "MEDIA_DECODE_ERROR",
+    MEDIA_NETWORK_ERROR = "MEDIA_NETWORK_ERROR",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Structured player error.
+ */
+export interface PlayerError {
+    /** Error code */
+    code: ErrorCode;
+    /** Error message */
+    message: string;
+    /** Whether error is fatal (unrecoverable) */
+    fatal: boolean;
+    /** Timestamp (milliseconds since epoch) */
+    timestamp: number;
+    /** Optional context (what was happening) */
+    context?: Record<string, any>;
+    /** Original error if wrapped */
+    originalError?: Error;
+}
+/**
+ * ErrorHandler options.
+ */
+export interface ErrorHandlerOptions {
+    /** Maximum error history to keep (default: 10) */
+    maxHistory?: number;
+}
+/**
+ * ErrorHandler manages all player errors with classification and history.
+ *
+ * Features:
+ * - Error classification (fatal vs recoverable)
+ * - Error code mapping
+ * - Error event emission
+ * - Error history tracking
+ * - Context capture
+ * - Logger integration
+ *
+ * @example
+ * ```ts
+ * const errorHandler = new ErrorHandler(eventBus, logger);
+ *
+ * // Handle native error
+ * try {
+ *   // Some operation
+ * } catch (error) {
+ *   errorHandler.handle(error as Error, {
+ *     operation: 'loadSource',
+ *     src: 'video.mp4'
+ *   });
+ * }
+ *
+ * // Throw specific error
+ * errorHandler.throw(
+ *   ErrorCode.SOURCE_NOT_SUPPORTED,
+ *   'MP4 files are not supported',
+ *   { fatal: true, context: { src: 'video.mp4' } }
+ * );
+ *
+ * // Check error history
+ * const lastError = errorHandler.getLastError();
+ * const hasFatal = errorHandler.hasFatalError();
+ * ```
+ */
+export declare class ErrorHandler {
+    /** Event bus for error emission */
+    private eventBus;
+    /** Logger for error logging */
+    private logger;
+    /** Error history */
+    private errors;
+    /** Maximum history size */
+    private maxHistory;
+    /**
+     * Create a new ErrorHandler.
+     *
+     * @param eventBus - Event bus for error emission
+     * @param logger - Logger for error logging
+     * @param options - Optional configuration
+     */
+    constructor(eventBus: EventBus, logger: Logger, options?: ErrorHandlerOptions);
+    /**
+     * Handle an error.
+     *
+     * Normalizes, logs, emits, and tracks the error.
+     *
+     * @param error - Error to handle (native or PlayerError)
+     * @param context - Optional context (what was happening)
+     * @returns Normalized PlayerError
+     *
+     * @example
+     * ```ts
+     * try {
+     *   loadVideo();
+     * } catch (error) {
+     *   errorHandler.handle(error as Error, { src: 'video.mp4' });
+     * }
+     * ```
+     */
+    handle(error: Error | PlayerError, context?: Record<string, any>): PlayerError;
+    /**
+     * Create and handle an error from code.
+     *
+     * @param code - Error code
+     * @param message - Error message
+     * @param options - Optional error options
+     * @returns Created PlayerError
+     *
+     * @example
+     * ```ts
+     * errorHandler.throw(
+     *   ErrorCode.SOURCE_NOT_SUPPORTED,
+     *   'MP4 not supported',
+     *   { fatal: true, context: { type: 'video/mp4' } }
+     * );
+     * ```
+     */
+    throw(code: ErrorCode, message: string, options?: {
+        fatal?: boolean;
+        context?: Record<string, any>;
+        originalError?: Error;
+    }): PlayerError;
+    /**
+     * Get error history.
+     *
+     * @returns Readonly copy of error history
+     *
+     * @example
+     * ```ts
+     * const history = errorHandler.getHistory();
+     * console.log(`${history.length} errors occurred`);
+     * ```
+     */
+    getHistory(): readonly PlayerError[];
+    /**
+     * Get last error that occurred.
+     *
+     * @returns Last error or null if none
+     *
+     * @example
+     * ```ts
+     * const lastError = errorHandler.getLastError();
+     * if (lastError?.fatal) {
+     *   showErrorMessage(lastError.message);
+     * }
+     * ```
+     */
+    getLastError(): PlayerError | null;
+    /**
+     * Clear error history.
+     *
+     * @example
+     * ```ts
+     * errorHandler.clearHistory();
+     * ```
+     */
+    clearHistory(): void;
+    /**
+     * Check if any fatal errors occurred.
+     *
+     * @returns True if any fatal error in history
+     *
+     * @example
+     * ```ts
+     * if (errorHandler.hasFatalError()) {
+     *   player.reset();
+     * }
+     * ```
+     */
+    hasFatalError(): boolean;
+    /**
+     * Normalize error to PlayerError.
+     * @private
+     */
+    private normalizeError;
+    /**
+     * Determine error code from native Error.
+     * @private
+     */
+    private getErrorCode;
+    /**
+     * Determine if error is fatal.
+     * @private
+     */
+    private isFatal;
+    /**
+     * Determine if error code is fatal.
+     * @private
+     */
+    private isFatalCode;
+    /**
+     * Type guard for PlayerError.
+     * @private
+     */
+    private isPlayerError;
+    /**
+     * Add error to history.
+     * @private
+     */
+    private addToHistory;
+    /**
+     * Log error with appropriate level.
+     * @private
+     */
+    private logError;
+}
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/events/event-bus.d.ts

@@ -0,0 +1,212 @@
+/**
+ * EventBus - Type-safe event system for Scarlett Player.
+ *
+ * Provides pub/sub event communication between player components and plugins
+ * with optional interceptors for event modification/cancellation.
+ *
+ * Target size: ~1KB
+ */
+import type { EventName, EventPayload, EventHandler, EventInterceptor, EventEmitterOptions } from '../types/events';
+/**
+ * EventBus provides type-safe event emission and subscription.
+ *
+ * Features:
+ * - Type-safe events based on PlayerEventMap
+ * - Event interceptors for modification/cancellation
+ * - One-time subscriptions with once()
+ * - Async event emission
+ * - Error handling for handlers
+ *
+ * @example
+ * ```ts
+ * const events = new EventBus();
+ *
+ * // Subscribe to event
+ * events.on('playback:play', () => {
+ *   console.log('Playing!');
+ * });
+ *
+ * // Emit event
+ * events.emit('playback:play', undefined);
+ *
+ * // Intercept events
+ * events.intercept('playback:timeupdate', (payload) => {
+ *   // Modify payload or return null to cancel
+ *   return { currentTime: Math.floor(payload.currentTime) };
+ * });
+ * ```
+ */
+export declare class EventBus {
+    /** Event listeners map */
+    private listeners;
+    /** One-time listeners (removed after first call) */
+    private onceListeners;
+    /** Event interceptors map */
+    private interceptors;
+    /** Configuration options */
+    private options;
+    /**
+     * Create a new EventBus.
+     *
+     * @param options - Optional configuration
+     */
+    constructor(options?: EventEmitterOptions);
+    /**
+     * Subscribe to an event.
+     *
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```ts
+     * const unsub = events.on('playback:play', () => {
+     *   console.log('Playing!');
+     * });
+     *
+     * // Later: unsubscribe
+     * unsub();
+     * ```
+     */
+    on<T extends EventName>(event: T, handler: EventHandler<T>): () => void;
+    /**
+     * Subscribe to an event once (auto-unsubscribe after first call).
+     *
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```ts
+     * events.once('player:ready', () => {
+     *   console.log('Player ready!');
+     * });
+     * ```
+     */
+    once<T extends EventName>(event: T, handler: EventHandler<T>): () => void;
+    /**
+     * Unsubscribe from an event.
+     *
+     * @param event - Event name
+     * @param handler - Event handler function to remove
+     *
+     * @example
+     * ```ts
+     * const handler = () => console.log('Playing!');
+     * events.on('playback:play', handler);
+     * events.off('playback:play', handler);
+     * ```
+     */
+    off<T extends EventName>(event: T, handler: EventHandler<T>): void;
+    /**
+     * Emit an event synchronously.
+     *
+     * Runs interceptors first, then calls all handlers.
+     *
+     * @param event - Event name
+     * @param payload - Event payload
+     *
+     * @example
+     * ```ts
+     * events.emit('playback:play', undefined);
+     * events.emit('playback:timeupdate', { currentTime: 10.5 });
+     * ```
+     */
+    emit<T extends EventName>(event: T, payload: EventPayload<T>): void;
+    /**
+     * Emit an event asynchronously (next tick).
+     *
+     * @param event - Event name
+     * @param payload - Event payload
+     * @returns Promise that resolves when all handlers complete
+     *
+     * @example
+     * ```ts
+     * await events.emitAsync('media:loaded', { src: 'video.mp4', type: 'video/mp4' });
+     * ```
+     */
+    emitAsync<T extends EventName>(event: T, payload: EventPayload<T>): Promise<void>;
+    /**
+     * Add an event interceptor.
+     *
+     * Interceptors run before handlers and can modify or cancel events.
+     *
+     * @param event - Event name
+     * @param interceptor - Interceptor function
+     * @returns Remove interceptor function
+     *
+     * @example
+     * ```ts
+     * events.intercept('playback:timeupdate', (payload) => {
+     *   // Round time to 2 decimals
+     *   return { currentTime: Math.round(payload.currentTime * 100) / 100 };
+     * });
+     *
+     * // Cancel events
+     * events.intercept('playback:play', (payload) => {
+     *   if (notReady) return null; // Cancel event
+     *   return payload;
+     * });
+     * ```
+     */
+    intercept<T extends EventName>(event: T, interceptor: EventInterceptor<T>): () => void;
+    /**
+     * Remove all listeners for an event (or all events if no event specified).
+     *
+     * @param event - Optional event name
+     *
+     * @example
+     * ```ts
+     * events.removeAllListeners('playback:play'); // Remove all playback:play listeners
+     * events.removeAllListeners(); // Remove ALL listeners
+     * ```
+     */
+    removeAllListeners(event?: EventName): void;
+    /**
+     * Get the number of listeners for an event.
+     *
+     * @param event - Event name
+     * @returns Number of listeners
+     *
+     * @example
+     * ```ts
+     * events.listenerCount('playback:play'); // 3
+     * ```
+     */
+    listenerCount(event: EventName): number;
+    /**
+     * Destroy event bus and cleanup all listeners/interceptors.
+     *
+     * @example
+     * ```ts
+     * events.destroy();
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Run interceptors synchronously.
+     * @private
+     */
+    private runInterceptors;
+    /**
+     * Run interceptors asynchronously.
+     * @private
+     */
+    private runInterceptorsAsync;
+    /**
+     * Safely call a handler with error handling.
+     * @private
+     */
+    private safeCallHandler;
+    /**
+     * Safely call a handler asynchronously with error handling.
+     * @private
+     */
+    private safeCallHandlerAsync;
+    /**
+     * Check if max listeners exceeded and warn.
+     * @private
+     */
+    private checkMaxListeners;
+}
+//# sourceMappingURL=event-bus.d.ts.map