@mediafox/core 1.2.8 → 1.2.10

package/src/utils/dispose.ts

@@ -0,0 +1,28 @@
+/**
+ * Safely calls return() on an AsyncGenerator if present, swallowing errors.
+ * Used to ensure iterators are properly cleaned up without leaking promises.
+ */
+export function safeAsyncReturn<T, TReturn = unknown, TNext = unknown>(
+  iterator: AsyncGenerator<T, TReturn, TNext> | null | undefined
+): void {
+  try {
+    // Intentionally do not await inside non-async dispose paths
+    // Some TS lib dom typings require a value argument
+    void iterator?.return?.(undefined as unknown as TReturn);
+  } catch {
+    // Ignore iterator return errors during cleanup
+  }
+}
+
+/**
+ * Clear interval/RAF ids safely.
+ */
+export function safeClearInterval(id: number | null): null {
+  if (id !== null) clearInterval(id);
+  return null;
+}
+
+export function safeCancelAnimationFrame(id: number | null): null {
+  if (id !== null) cancelAnimationFrame(id);
+  return null;
+}

package/src/utils/equal.ts

@@ -0,0 +1,33 @@
+// Lightweight deep equality for simple JSON-like structures used in state
+export function isDeepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return a === b;
+
+  // Arrays
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!isDeepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+
+  // Objects
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const ak = Object.keys(a as Record<string, unknown>);
+    const bk = Object.keys(b as Record<string, unknown>);
+    if (ak.length !== bk.length) return false;
+    for (const k of ak) {
+      if (!Object.hasOwn(b, k)) return false;
+      if (!isDeepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k])) return false;
+    }
+    return true;
+  }
+
+  return false;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && (v as object).constructor === Object;
+}

package/src/utils/errors.ts

@@ -0,0 +1,74 @@
+export enum ErrorCode {
+  MEDIA_NOT_SUPPORTED = 'MEDIA_NOT_SUPPORTED',
+  MEDIA_LOAD_FAILED = 'MEDIA_LOAD_FAILED',
+  DECODE_ERROR = 'DECODE_ERROR',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  PERMISSION_DENIED = 'PERMISSION_DENIED',
+  PLAYBACK_ERROR = 'PLAYBACK_ERROR',
+  TRACK_NOT_FOUND = 'TRACK_NOT_FOUND',
+  INVALID_STATE = 'INVALID_STATE',
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
+}
+
+export class MediaFoxError extends Error {
+  code: ErrorCode;
+  details?: unknown;
+
+  constructor(code: ErrorCode, message: string, details?: unknown) {
+    super(message);
+    this.name = 'MediaFoxError';
+    this.code = code;
+    this.details = details;
+  }
+
+  static mediaNotSupported(message = 'Media format not supported', details?: unknown): MediaFoxError {
+    return new MediaFoxError(ErrorCode.MEDIA_NOT_SUPPORTED, message, details);
+  }
+
+  static mediaLoadFailed(message = 'Failed to load media', details?: unknown): MediaFoxError {
+    return new MediaFoxError(ErrorCode.MEDIA_LOAD_FAILED, message, details);
+  }
+
+  static decodeError(message = 'Failed to decode media', details?: unknown): MediaFoxError {
+    return new MediaFoxError(ErrorCode.DECODE_ERROR, message, details);
+  }
+
+  static networkError(message = 'Network error occurred', details?: unknown): MediaFoxError {
+    return new MediaFoxError(ErrorCode.NETWORK_ERROR, message, details);
+  }
+
+  static permissionDenied(message = 'Permission denied', details?: unknown): MediaFoxError {
+    return new MediaFoxError(ErrorCode.PERMISSION_DENIED, message, details);
+  }
+
+  static playbackError(message = 'Playback error occurred', details?: unknown): MediaFoxError {
+    return new MediaFoxError(ErrorCode.PLAYBACK_ERROR, message, details);
+  }
+
+  static trackNotFound(message = 'Track not found', details?: unknown): MediaFoxError {
+    return new MediaFoxError(ErrorCode.TRACK_NOT_FOUND, message, details);
+  }
+
+  static invalidState(message = 'Invalid player state', details?: unknown): MediaFoxError {
+    return new MediaFoxError(ErrorCode.INVALID_STATE, message, details);
+  }
+
+  static unknownError(message = 'Unknown error occurred', details?: unknown): MediaFoxError {
+    return new MediaFoxError(ErrorCode.UNKNOWN_ERROR, message, details);
+  }
+}
+
+/**
+ * Wrap an error with additional context
+ */
+export function wrapError(error: unknown, context: string): MediaFoxError {
+  if (error instanceof MediaFoxError) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return new MediaFoxError(ErrorCode.UNKNOWN_ERROR, `${context}: ${error.message}`, { originalError: error });
+  }
+
+  return new MediaFoxError(ErrorCode.UNKNOWN_ERROR, `${context}: ${String(error)}`, { originalError: error });
+}

package/src/utils/logger.ts

@@ -0,0 +1,50 @@
+/**
+ * Simple logger utility for MediaFox
+ */
+
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+  NONE = 4,
+}
+
+let logLevel: LogLevel = LogLevel.WARN;
+const logPrefix = '[MediaFox]';
+
+export function setLogLevel(level: LogLevel): void {
+  logLevel = level;
+}
+
+export function debug(message: string, ...args: unknown[]): void {
+  if (logLevel <= LogLevel.DEBUG) {
+    console.debug(`${logPrefix} ${message}`, ...args);
+  }
+}
+
+export function info(message: string, ...args: unknown[]): void {
+  if (logLevel <= LogLevel.INFO) {
+    console.info(`${logPrefix} ${message}`, ...args);
+  }
+}
+
+export function warn(message: string, ...args: unknown[]): void {
+  if (logLevel <= LogLevel.WARN) {
+    console.warn(`${logPrefix} ${message}`, ...args);
+  }
+}
+
+export function error(message: string, ...args: unknown[]): void {
+  if (logLevel <= LogLevel.ERROR) {
+    console.error(`${logPrefix} ${message}`, ...args);
+  }
+}
+
+export const logger = {
+  setLevel: setLogLevel,
+  debug,
+  info,
+  warn,
+  error,
+};

package/src/utils/time.ts

@@ -0,0 +1,157 @@
+/**
+ * Format seconds into a human-readable time string
+ * @param seconds - Time in seconds
+ * @param showMilliseconds - Whether to show milliseconds
+ * @returns Formatted time string (e.g., "1:23:45" or "23:45.123")
+ */
+export function formatTime(seconds: number, showMilliseconds = false): string {
+  const absSeconds = Math.abs(seconds);
+  const hours = Math.floor(absSeconds / 3600);
+  const minutes = Math.floor((absSeconds % 3600) / 60);
+  const secs = Math.floor(absSeconds % 60);
+  const ms = Math.floor((absSeconds % 1) * 1000);
+
+  let result = '';
+
+  if (seconds < 0) {
+    result = '-';
+  }
+
+  if (hours > 0) {
+    result += `${hours}:${minutes.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
+  } else {
+    result += `${minutes}:${secs.toString().padStart(2, '0')}`;
+  }
+
+  if (showMilliseconds) {
+    result += `.${ms.toString().padStart(3, '0')}`;
+  }
+
+  return result;
+}
+
+/**
+ * Parse a time string into seconds
+ * @param timeString - Time string (e.g., "1:23:45", "23:45", "45")
+ * @returns Time in seconds
+ */
+export function parseTime(timeString: string): number {
+  const parts = timeString.trim().split(':').map(Number);
+
+  if (parts.some(Number.isNaN)) {
+    throw new Error('Invalid time string');
+  }
+
+  let seconds = 0;
+
+  if (parts.length === 3) {
+    // HH:MM:SS
+    seconds = parts[0] * 3600 + parts[1] * 60 + parts[2];
+  } else if (parts.length === 2) {
+    // MM:SS
+    seconds = parts[0] * 60 + parts[1];
+  } else if (parts.length === 1) {
+    // SS
+    seconds = parts[0];
+  } else {
+    throw new Error('Invalid time format');
+  }
+
+  return seconds;
+}
+
+/**
+ * Get frame number from time
+ * @param time - Time in seconds
+ * @param frameRate - Frame rate in Hz
+ * @returns Frame number
+ */
+export function timeToFrame(time: number, frameRate: number): number {
+  return Math.floor(time * frameRate);
+}
+
+/**
+ * Get time from frame number
+ * @param frame - Frame number
+ * @param frameRate - Frame rate in Hz
+ * @returns Time in seconds
+ */
+export function frameToTime(frame: number, frameRate: number): number {
+  return frame / frameRate;
+}
+
+/**
+ * Clamp a value between min and max
+ * @param value - Value to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped value
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+/**
+ * Check if two time ranges overlap
+ * @param range1 - First time range
+ * @param range2 - Second time range
+ * @returns True if ranges overlap
+ */
+export function timeRangesOverlap(
+  range1: { start: number; end: number },
+  range2: { start: number; end: number }
+): boolean {
+  return range1.start < range2.end && range2.start < range1.end;
+}
+
+/**
+ * Merge overlapping time ranges
+ * @param ranges - Array of time ranges
+ * @returns Merged time ranges
+ */
+export function mergeTimeRanges(ranges: Array<{ start: number; end: number }>): Array<{ start: number; end: number }> {
+  if (ranges.length === 0) return [];
+
+  const sorted = [...ranges].sort((a, b) => a.start - b.start);
+  const merged: Array<{ start: number; end: number }> = [sorted[0]];
+
+  for (let i = 1; i < sorted.length; i++) {
+    const last = merged[merged.length - 1];
+    const current = sorted[i];
+
+    if (current.start <= last.end) {
+      last.end = Math.max(last.end, current.end);
+    } else {
+      merged.push(current);
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Calculate total buffered duration
+ * @param ranges - Array of time ranges
+ * @returns Total duration in seconds
+ */
+export function totalBufferedDuration(ranges: Array<{ start: number; end: number }>): number {
+  return ranges.reduce((total, range) => total + (range.end - range.start), 0);
+}
+
+/**
+ * Find the buffered range containing a specific time
+ * @param ranges - Array of time ranges
+ * @param time - Time to search for
+ * @returns The containing range or null
+ */
+export function findBufferedRange(
+  ranges: Array<{ start: number; end: number }>,
+  time: number
+): { start: number; end: number } | null {
+  for (const range of ranges) {
+    if (time >= range.start && time < range.end) {
+      return range;
+    }
+  }
+  return null;
+}