@therealtinhtute/baroiplayer 1.0.8 → 1.2.0

package/src/lib/__tests__/async-utils.test.ts

@@ -0,0 +1,291 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { batch, createThrottledValue, debounce, throttle } from "../async-utils"
+
+describe("async-utils", () => {
+	describe("throttle", () => {
+		beforeEach(() => {
+			vi.useFakeTimers()
+		})
+
+		afterEach(() => {
+			vi.useRealTimers()
+		})
+
+		it("should call function immediately on first call when leading is true", () => {
+			const fn = vi.fn()
+			const throttled = throttle(fn, 100)
+
+			throttled()
+			throttled()
+			throttled()
+
+			expect(fn).toHaveBeenCalledTimes(1)
+		})
+
+		it("should not call function immediately when leading is false", () => {
+			const fn = vi.fn()
+			const throttled = throttle(fn, 100, { leading: false })
+
+			throttled()
+			throttled()
+
+			expect(fn).not.toHaveBeenCalled()
+
+			vi.advanceTimersByTime(100)
+
+			// Only the last call should trigger
+			expect(fn).toHaveBeenCalledTimes(1)
+		})
+
+		it("should call function again after limit has passed", () => {
+			const fn = vi.fn()
+			const throttled = throttle(fn, 100)
+
+			throttled()
+			expect(fn).toHaveBeenCalledTimes(1)
+
+			// Advance time but not enough
+			vi.advanceTimersByTime(50)
+			throttled()
+			expect(fn).toHaveBeenCalledTimes(1)
+
+			// Advance remaining time
+			vi.advanceTimersByTime(60)
+			throttled()
+			expect(fn).toHaveBeenCalledTimes(2)
+		})
+
+		it("should call trailing edge after limit when trailing is true", () => {
+			const fn = vi.fn()
+			const throttled = throttle(fn, 100, { trailing: true })
+
+			throttled()
+			throttled()
+			throttled()
+			expect(fn).toHaveBeenCalledTimes(1)
+
+			// Advance to just before trailing would fire
+			vi.advanceTimersByTime(99)
+			expect(fn).toHaveBeenCalledTimes(1)
+
+			// Advance past the threshold
+			vi.advanceTimersByTime(2)
+			expect(fn).toHaveBeenCalledTimes(2)
+		})
+
+		it("should pass arguments correctly", () => {
+			const fn = vi.fn()
+			const throttled = throttle(fn, 100)
+
+			throttled("arg1", 2, { key: "value" })
+			vi.advanceTimersByTime(150)
+			throttled("arg2", 3)
+
+			expect(fn).toHaveBeenCalledWith("arg1", 2, { key: "value" })
+			expect(fn).toHaveBeenCalledWith("arg2", 3)
+		})
+
+		it("should handle concurrent calls with different limits", () => {
+			const fn1 = vi.fn()
+			const fn2 = vi.fn()
+			const throttled1 = throttle(fn1, 100)
+			const throttled2 = throttle(fn2, 50)
+
+			throttled1()
+			throttled2()
+			throttled1()
+			throttled2()
+
+			expect(fn1).toHaveBeenCalledTimes(1)
+			expect(fn2).toHaveBeenCalledTimes(1)
+
+			vi.advanceTimersByTime(60)
+			throttled2()
+			expect(fn2).toHaveBeenCalledTimes(2)
+		})
+	})
+
+	describe("debounce", () => {
+		beforeEach(() => {
+			vi.useFakeTimers()
+		})
+
+		afterEach(() => {
+			vi.useRealTimers()
+		})
+
+		it("should delay function call until wait period has passed", () => {
+			const fn = vi.fn()
+			const debounced = debounce(fn, 100)
+
+			debounced()
+			expect(fn).not.toHaveBeenCalled()
+
+			vi.advanceTimersByTime(50)
+			expect(fn).not.toHaveBeenCalled()
+
+			vi.advanceTimersByTime(60)
+			expect(fn).toHaveBeenCalledTimes(1)
+		})
+
+		it("should call immediately when immediate is true", () => {
+			const fn = vi.fn()
+			const debounced = debounce(fn, 100, { immediate: true })
+
+			debounced()
+			expect(fn).toHaveBeenCalledTimes(1)
+
+			// Subsequent calls within wait period should not trigger
+			debounced()
+			expect(fn).toHaveBeenCalledTimes(1)
+
+			vi.advanceTimersByTime(100)
+			// Still should be 1 because the wait period reset the timer
+			debounced()
+			expect(fn).toHaveBeenCalledTimes(2)
+		})
+
+		it("should reset timer on subsequent calls", () => {
+			const fn = vi.fn()
+			const debounced = debounce(fn, 100)
+
+			debounced()
+			expect(fn).not.toHaveBeenCalled()
+
+			vi.advanceTimersByTime(50)
+			debounced() // Reset timer
+			expect(fn).not.toHaveBeenCalled()
+
+			vi.advanceTimersByTime(60) // 110 total, but reset at 50
+			expect(fn).not.toHaveBeenCalled()
+
+			vi.advanceTimersByTime(50) // 160 total
+			expect(fn).toHaveBeenCalledTimes(1)
+		})
+
+		it("should pass arguments correctly", () => {
+			const fn = vi.fn()
+			const debounced = debounce(fn, 100)
+
+			debounced("arg1", 2)
+			vi.advanceTimersByTime(100)
+
+			expect(fn).toHaveBeenCalledWith("arg1", 2)
+		})
+
+		it("should return value from immediate call", () => {
+			const fn = vi.fn().mockReturnValue("result")
+			const debounced = debounce(fn, 100, { immediate: true })
+
+			const result = debounced()
+
+			expect(result).toBe("result")
+		})
+	})
+
+	describe("createThrottledValue", () => {
+		beforeEach(() => {
+			vi.useFakeTimers()
+		})
+
+		afterEach(() => {
+			vi.useRealTimers()
+		})
+
+		it("should return initial value initially", () => {
+			const { getThrottledValue } = createThrottledValue(0, 100)
+			expect(getThrottledValue()).toBe(0)
+		})
+
+		it("should update throttled value after limit", () => {
+			const { update, getThrottledValue } = createThrottledValue(0, 100)
+
+			update(50)
+			expect(getThrottledValue()).toBe(0) // Not yet updated
+
+			vi.advanceTimersByTime(100)
+			expect(getThrottledValue()).toBe(50)
+		})
+
+		it("should always return latest value", () => {
+			const { update, getLatestValue } = createThrottledValue(0, 100)
+
+			update(100)
+			expect(getLatestValue()).toBe(100)
+		})
+
+		it("should skip intermediate updates", () => {
+			const { update, getThrottledValue, forceUpdate } = createThrottledValue(0, 100)
+
+			update(10)
+			update(20)
+			update(30)
+			update(40)
+			update(50)
+
+			expect(getThrottledValue()).toBe(0) // Not yet
+
+			// Force update for testing purposes
+			forceUpdate()
+			expect(getThrottledValue()).toBe(50) // Only last value
+		})
+
+		it("should allow manual force update", () => {
+			const { update, getThrottledValue, forceUpdate } = createThrottledValue(0, 100)
+
+			update(75)
+			expect(getThrottledValue()).toBe(0)
+
+			forceUpdate()
+			expect(getThrottledValue()).toBe(75)
+		})
+	})
+
+	describe("batch", () => {
+		beforeEach(() => {
+			vi.useFakeTimers()
+		})
+
+		afterEach(() => {
+			vi.useRealTimers()
+		})
+
+		it("should batch multiple calls", () => {
+			const fn = vi.fn()
+			const batched = batch(fn)
+
+			batched(1)
+			batched(2)
+			batched(3)
+
+			expect(fn).not.toHaveBeenCalled()
+
+			vi.advanceTimersByTime(0) // Microtask
+			expect(fn).toHaveBeenCalledTimes(1)
+			expect(fn).toHaveBeenCalledWith([[1], [2], [3]])
+		})
+
+		it("should handle single call", () => {
+			const fn = vi.fn()
+			const batched = batch(fn)
+
+			batched("single")
+			vi.advanceTimersByTime(0)
+
+			expect(fn).toHaveBeenCalledWith([["single"]])
+		})
+
+		it("should reset batch after each execution", () => {
+			const fn = vi.fn()
+			const batched = batch(fn)
+
+			batched(1)
+			vi.advanceTimersByTime(0)
+			expect(fn).toHaveBeenCalledWith([[1]])
+
+			batched(2)
+			vi.advanceTimersByTime(0)
+			expect(fn).toHaveBeenCalledWith([[2]])
+		})
+	})
+})

package/src/lib/async-utils.ts

@@ -0,0 +1,194 @@
+/**
+ * Async utilities for performance optimization
+ * Provides throttle and debounce functions for controlling event frequency
+ */
+
+/**
+ * Throttle function that ensures a function is only called at most once
+ * within a specified time period. Includes options for leading and trailing calls.
+ *
+ * @param func - The function to throttle
+ * @param limit - The time limit in milliseconds
+ * @param options - Options for leading/trailing edge calls
+ * @returns The throttled function
+ *
+ * @example
+ * // Throttle a click handler to at most once per 250ms
+ * const throttledClick = throttle(handleClick, 250);
+ *
+ * // For timeupdate events with leading edge disabled
+ * const throttledUpdate = throttle(handleUpdate, 250, { leading: false });
+ */
+export function throttle<T extends (...args: Parameters<T>) => ReturnType<T>>(
+	func: T,
+	limit: number,
+	options: { leading?: boolean; trailing?: boolean } = {
+		leading: true,
+		trailing: true
+	}
+): T {
+	let lastResult: ReturnType<T> | undefined
+	let lastCallTime = 0
+	let timeoutId: ReturnType<typeof setTimeout> | null = null
+	const { leading = true, trailing = true } = options
+
+	return ((...args: Parameters<T>): ReturnType<T> => {
+		const now = Date.now()
+		const remaining = limit - (now - lastCallTime)
+
+		const call = () => {
+			lastCallTime = Date.now()
+			timeoutId = null
+			lastResult = func(...args)
+		}
+
+		if (!lastCallTime) {
+			// First call - respect leading option
+			if (leading) {
+				lastResult = func(...args)
+			}
+			lastCallTime = now
+		} else if (remaining <= 0) {
+			// Time limit reached
+			if (timeoutId) {
+				clearTimeout(timeoutId)
+				timeoutId = null
+			}
+			lastResult = func(...args)
+			lastCallTime = now
+		} else if (trailing && !timeoutId) {
+			// Schedule trailing call
+			timeoutId = setTimeout(() => call(), remaining)
+		}
+
+		return lastResult as ReturnType<T>
+	}) as T
+}
+
+/**
+ * Debounce function that delays calling a function until after a specified
+ * wait period has elapsed since the last time the debounced function was called.
+ *
+ * @param func - The function to debounce
+ * @param wait - The wait period in milliseconds
+ * @param options - Options for immediate invocation
+ * @returns The debounced function
+ *
+ * @example
+ * // Debounce a resize handler
+ * const debouncedResize = debounce(handleResize, 150);
+ *
+ * // Debounce with immediate option for form validation
+ * const immediateValidate = debounce(validateForm, 300, { immediate: true });
+ */
+export function debounce<T extends (...args: Parameters<T>) => ReturnType<T>>(
+	func: T,
+	wait: number,
+	options: { immediate?: boolean } = {}
+): T {
+	let timeoutId: ReturnType<typeof setTimeout> | null = null
+	const { immediate = false } = options
+
+	return ((...args: Parameters<T>): ReturnType<T> => {
+		const call = () => {
+			timeoutId = null
+			return func(...args)
+		}
+
+		const later = () => {
+			timeoutId = null
+			if (!immediate) {
+				return func(...args)
+			}
+		}
+
+		const callNow = immediate && !timeoutId
+		const result = callNow ? func(...args) : undefined
+
+		if (timeoutId) {
+			clearTimeout(timeoutId)
+		}
+
+		timeoutId = setTimeout(immediate ? later : call, wait)
+
+		return result as ReturnType<T>
+	}) as T
+}
+
+/**
+ * Creates a throttled callback that only updates the value at most once
+ * per interval, but always returns the latest value when called.
+ * Useful for UI updates that should be throttled but need to show final state.
+ *
+ * @param initialValue - The initial value
+ * @param limit - The time limit in milliseconds
+ * @returns An object with update function and getter functions
+ *
+ * @example
+ * const { update, getThrottledValue, getLatestValue } = createThrottledValue(0, 250);
+ */
+export function createThrottledValue<T>(initialValue: T, limit: number) {
+	let latestValue = initialValue
+	let lastUpdateTime = 0
+	let throttledValue = initialValue
+
+	const update = (value: T) => {
+		latestValue = value
+		const now = Date.now()
+		if (now - lastUpdateTime >= limit) {
+			throttledValue = value
+			lastUpdateTime = now
+		}
+	}
+
+	const getThrottledValue = () => throttledValue
+	const getLatestValue = () => latestValue
+	const forceUpdate = () => {
+		throttledValue = latestValue
+		lastUpdateTime = Date.now()
+	}
+
+	return { update, getThrottledValue, getLatestValue, forceUpdate }
+}
+
+/**
+ * Batch multiple rapid calls into a single call at the end of the event loop.
+ * Useful for React state updates that should be batched.
+ *
+ * @param func - The function to call with batched arguments
+ * @returns A function that batches arguments and calls the original function once
+ *
+ * @example
+ * const batchUpdate = batch((updates) => {
+ *   updates.forEach(update => setState(prev => ({ ...prev, ...update })));
+ * });
+ *
+ * // Multiple rapid calls will be batched
+ * batchUpdate({ a: 1 });
+ * batchUpdate({ a: 2 });
+ * batchUpdate({ a: 3 });
+ */
+export function batch<T extends (...args: Parameters<T>) => void>(
+	func: (args: Parameters<T>[]) => void
+): (...args: Parameters<T>) => void {
+	let batchedArgs: Parameters<T>[] = []
+	let scheduled = false
+
+	const flush = () => {
+		if (batchedArgs.length > 0) {
+			func(batchedArgs)
+			batchedArgs = []
+		}
+		scheduled = false
+	}
+
+	return (...args: Parameters<T>) => {
+		batchedArgs.push(args)
+		if (!scheduled) {
+			scheduled = true
+			// Use setImmediate/setTimeout pattern for cross-environment compatibility
+			// In browsers this schedules as a macrotask, in tests with fake timers it will fire
+			setTimeout(() => flush(), 0)
+		}
+	}
+}

package/src/lib/deprecation.ts

@@ -20,8 +20,8 @@ export function showDeprecationWarning(
 
 	console.warn(
 		`⚠️ [BaroiPlayer] DEPRECATION WARNING: ${itemName} is deprecated and will be removed in v${version}.` +
-		`\n   Please replace it with: ${replacement}` +
-		`\n   See https://github.com/baroi/baroiplayer/blob/main/MIGRATION.md for migration guide.`
+			`\n   Please replace it with: ${replacement}` +
+			`\n   See https://github.com/baroi/baroiplayer/blob/main/MIGRATION.md for migration guide.`
 	)
 }
 
@@ -33,7 +33,7 @@ export function createDeprecatedComponent<T>(
 	const DeprecatedComponent = component as any
 
 	// Add deprecation warning to the component
-	if (typeof DeprecatedComponent === 'function') {
+	if (typeof DeprecatedComponent === "function") {
 		const originalComponent = DeprecatedComponent
 		const WrappedComponent = function (props: any) {
 			showDeprecationWarning(ComponentName, replacement)
@@ -48,4 +48,4 @@ export function createDeprecatedComponent<T>(
 	}
 
 	return component
-}
+}

package/src/lib/index.ts

@@ -1,3 +1,4 @@
 // Utility functions
-export { formatTime, parseTime } from "./format-time";
-export { cn } from "./utils";
+export { formatTime, parseTime } from "./format-time"
+export { cn } from "./utils"
+export { throttle, debounce, createThrottledValue, batch } from "./async-utils"

package/src/lib/utils.ts

@@ -1,6 +1,6 @@
-import { type ClassValue, clsx } from 'clsx';
-import { twMerge } from 'tailwind-merge';
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
 
 export function cn(...inputs: ClassValue[]) {
-  return twMerge(clsx(inputs));
+	return twMerge(clsx(inputs))
 }

package/src/styles/globals.css

@@ -27,7 +27,7 @@
 	--media-text-muted: oklch(60% 0.01 240);
 
 	/* Control States */
-	--media-control-idle: oklch(68% 0.20 142);
+	--media-control-idle: oklch(68% 0.2 142);
 	--media-control-hover: oklch(85% 0.08 240);
 	--media-control-active: oklch(72% 0.15 30);
 	--media-control-disabled: oklch(45% 0.005 240);
@@ -62,7 +62,7 @@
 
 body {
 	margin: 0;
-	font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+	font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
 	background-color: var(--media-bg);
 	color: var(--media-text-primary);
 	line-height: 1.5;
@@ -459,4 +459,4 @@ body {
 	.media-player-error {
 		display: none;
 	}
-}
+}