@freqhole/playlistz 0.0.1

package/src/services/imageService.ts

@@ -0,0 +1,365 @@
+// Image Service for Album Art and Playlist Covers
+// Handles extraction, processing, and management of images
+
+import type { Song, Playlist } from "../types/playlist.js";
+
+export interface ImageProcessingResult {
+  success: boolean;
+  imageData?: ArrayBuffer;
+  thumbnailData?: ArrayBuffer;
+  error?: string;
+  metadata?: {
+    width: number;
+    height: number;
+    format: string;
+    size: number;
+  };
+}
+
+export interface ImageUrlResult {
+  thumbnailUrl: string;
+  fullSizeUrl: string;
+}
+
+export interface AlbumArtExtractionResult {
+  success: boolean;
+  albumArt?: string;
+  error?: string;
+}
+
+// Extract album art from audio file using ID3 tags
+export async function extractAlbumArt(
+  file: File
+): Promise<AlbumArtExtractionResult> {
+  try {
+    // Read file as ArrayBuffer for ID3 parsing
+    const buffer = await file.arrayBuffer();
+    const view = new DataView(buffer);
+
+    // Check for ID3v2 tag (starts with "ID3")
+    if (buffer.byteLength < 10) {
+      return { success: false, error: "File too small to contain ID3 tags" };
+    }
+
+    const id3Header = String.fromCharCode(
+      view.getUint8(0),
+      view.getUint8(1),
+      view.getUint8(2)
+    );
+    if (id3Header !== "ID3") {
+      return { success: false, error: "No ID3v2 tag found" };
+    }
+
+    // Parse ID3v2 header
+    const majorVersion = view.getUint8(3);
+    // const minorVersion = view.getUint8(4);
+    // const flags = view.getUint8(5);
+
+    // Calculate tag size (synchsafe integer)
+    const tagSize =
+      ((view.getUint8(6) & 0x7f) << 21) |
+      ((view.getUint8(7) & 0x7f) << 14) |
+      ((view.getUint8(8) & 0x7f) << 7) |
+      (view.getUint8(9) & 0x7f);
+
+    let offset = 10;
+    const endOffset = Math.min(10 + tagSize, buffer.byteLength);
+
+    // Search for APIC frame (Attached Picture)
+    while (offset < endOffset - 10) {
+      // Read frame header
+      const frameId = String.fromCharCode(
+        view.getUint8(offset),
+        view.getUint8(offset + 1),
+        view.getUint8(offset + 2),
+        view.getUint8(offset + 3)
+      );
+
+      if (frameId === "APIC") {
+        // Found album art frame
+        const frameSize =
+          majorVersion === 4
+            ? // ID3v2.4 uses synchsafe integers
+              ((view.getUint8(offset + 4) & 0x7f) << 21) |
+              ((view.getUint8(offset + 5) & 0x7f) << 14) |
+              ((view.getUint8(offset + 6) & 0x7f) << 7) |
+              (view.getUint8(offset + 7) & 0x7f)
+            : // ID3v2.3 uses regular integers
+              (view.getUint8(offset + 4) << 24) |
+              (view.getUint8(offset + 5) << 16) |
+              (view.getUint8(offset + 6) << 8) |
+              view.getUint8(offset + 7);
+
+        // const frameFlags = (view.getUint8(offset + 8) << 8) | view.getUint8(offset + 9);
+        let frameOffset = offset + 10;
+
+        // Skip encoding byte
+        frameOffset++;
+
+        // Read MIME type (null-terminated)
+        let mimeType = "";
+        while (frameOffset < endOffset && view.getUint8(frameOffset) !== 0) {
+          mimeType += String.fromCharCode(view.getUint8(frameOffset));
+          frameOffset++;
+        }
+        frameOffset++; // Skip null terminator
+
+        // Skip picture type byte
+        frameOffset++;
+
+        // Skip description (null-terminated)
+        while (frameOffset < endOffset && view.getUint8(frameOffset) !== 0) {
+          frameOffset++;
+        }
+        frameOffset++; // Skip null terminator
+
+        // Extract image data
+        const imageDataSize = frameSize - (frameOffset - offset - 10);
+        if (
+          imageDataSize > 0 &&
+          frameOffset + imageDataSize <= buffer.byteLength
+        ) {
+          const imageData = buffer.slice(
+            frameOffset,
+            frameOffset + imageDataSize
+          );
+          const blob = new Blob([imageData], { type: mimeType });
+          const albumArt = URL.createObjectURL(blob);
+
+          return { success: true, albumArt };
+        }
+      }
+
+      // Move to next frame
+      const frameSize =
+        majorVersion === 4
+          ? ((view.getUint8(offset + 4) & 0x7f) << 21) |
+            ((view.getUint8(offset + 5) & 0x7f) << 14) |
+            ((view.getUint8(offset + 6) & 0x7f) << 7) |
+            (view.getUint8(offset + 7) & 0x7f)
+          : (view.getUint8(offset + 4) << 24) |
+            (view.getUint8(offset + 5) << 16) |
+            (view.getUint8(offset + 6) << 8) |
+            view.getUint8(offset + 7);
+
+      offset += 10 + frameSize;
+    }
+
+    return { success: false, error: "No album art found in ID3 tags" };
+  } catch (error) {
+    console.error("Error extracting album art:", error);
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+
+// Process uploaded image file for playlist cover
+export async function processPlaylistCover(
+  file: File
+): Promise<ImageProcessingResult> {
+  try {
+    if (!file.type.startsWith("image/")) {
+      return { success: false, error: "File is not an image" };
+    }
+
+    // Validate file size (max 10MB)
+    const maxSize = 10 * 1024 * 1024;
+    if (file.size > maxSize) {
+      return { success: false, error: "Image file too large (max 10MB)" };
+    }
+
+    // Store original image data as ArrayBuffer
+    const imageData = await file.arrayBuffer();
+
+    // Create image element to get dimensions and create thumbnail
+    const img = new Image();
+    const tempUrl = URL.createObjectURL(file);
+
+    return new Promise((resolve) => {
+      img.onload = async () => {
+        try {
+          const metadata = {
+            width: img.width,
+            height: img.height,
+            format: file.type,
+            size: file.size,
+          };
+
+          // Create thumbnail data (300x300 max)
+          const thumbnailData = await createThumbnailData(
+            img,
+            300,
+            300,
+            file.type
+          );
+
+          // Clean up temporary URL
+          URL.revokeObjectURL(tempUrl);
+
+          resolve({
+            success: true,
+            imageData,
+            thumbnailData,
+            metadata,
+          });
+        } catch (error) {
+          URL.revokeObjectURL(tempUrl);
+          resolve({
+            success: false,
+            error: error instanceof Error ? error.message : "Processing failed",
+          });
+        }
+      };
+
+      img.onerror = () => {
+        URL.revokeObjectURL(tempUrl);
+        resolve({ success: false, error: "Invalid image file" });
+      };
+
+      img.src = tempUrl;
+    });
+  } catch (error) {
+    console.error("Error processing playlist cover:", error);
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+
+// Create thumbnail data as ArrayBuffer from image element
+async function createThumbnailData(
+  img: HTMLImageElement,
+  maxWidth: number,
+  maxHeight: number,
+  mimeType: string = "image/jpeg"
+): Promise<ArrayBuffer> {
+  const canvas = document.createElement("canvas");
+  const ctx = canvas.getContext("2d");
+
+  if (!ctx) {
+    throw new Error("Cannot create canvas context");
+  }
+
+  // Calculate thumbnail dimensions (maintain aspect ratio)
+  let { width, height } = img;
+
+  if (width > maxWidth || height > maxHeight) {
+    const ratio = Math.min(maxWidth / width, maxHeight / height);
+    width *= ratio;
+    height *= ratio;
+  }
+
+  canvas.width = width;
+  canvas.height = height;
+
+  // Draw image to canvas
+  ctx.drawImage(img, 0, 0, width, height);
+
+  // Convert to ArrayBuffer
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      async (blob) => {
+        if (blob) {
+          const arrayBuffer = await blob.arrayBuffer();
+          resolve(arrayBuffer);
+        } else {
+          reject(new Error("Failed to create thumbnail data"));
+        }
+      },
+      mimeType,
+      0.8
+    );
+  });
+}
+
+// Validate image file type and size
+export function validateImageFile(file: File): {
+  valid: boolean;
+  error?: string;
+} {
+  const allowedTypes = ["image/jpeg", "image/png", "image/gif", "image/webp"];
+  const maxSize = 10 * 1024 * 1024; // 10MB
+
+  if (!allowedTypes.includes(file.type)) {
+    return {
+      valid: false,
+      error: "Unsupported image format. Use JPEG, PNG, GIF, or WebP.",
+    };
+  }
+
+  if (file.size > maxSize) {
+    return {
+      valid: false,
+      error: "Image file too large. Maximum size is 10MB.",
+    };
+  }
+
+  return { valid: true };
+}
+
+// Clean up object URLs to prevent memory leaks
+export function cleanupImageUrl(url: string): void {
+  if (url.startsWith("blob:")) {
+    URL.revokeObjectURL(url);
+  }
+}
+
+// Convert stored image data to blob URL for display
+export function createImageUrlFromData(
+  imageData: ArrayBuffer,
+  mimeType: string = "image/jpeg"
+): string {
+  const blob = new Blob([imageData], { type: mimeType });
+  return URL.createObjectURL(blob);
+}
+
+// Create URLs for both thumbnail and full-size images
+export function createImageUrlsFromData(
+  thumbnailData: ArrayBuffer,
+  fullSizeData: ArrayBuffer,
+  mimeType: string = "image/jpeg"
+): ImageUrlResult {
+  const thumbnailBlob = new Blob([thumbnailData], { type: mimeType });
+  const fullSizeBlob = new Blob([fullSizeData], { type: mimeType });
+
+  return {
+    thumbnailUrl: URL.createObjectURL(thumbnailBlob),
+    fullSizeUrl: URL.createObjectURL(fullSizeBlob),
+  };
+}
+
+// Helper to determine which image size to use for different contexts
+export function getImageUrlForContext(
+  item: Song | Playlist,
+  context: "thumbnail" | "background" | "modal" = "thumbnail"
+): string | null {
+  if (!item?.imageType && !item?.imageFilePath) return null;
+
+  const { thumbnailData, imageData, imageType, imageFilePath } = item;
+
+  // For backgrounds and modals, prefer full-size, fallback to thumbnail
+  if (context === "background" || context === "modal") {
+    if (imageData) {
+      return createImageUrlFromData(imageData, imageType ?? "image/jpeg");
+    } else if (thumbnailData) {
+      return createImageUrlFromData(thumbnailData, imageType ?? "image/jpeg");
+    }
+  }
+
+  // For thumbnails, prefer thumbnail size, fallback to full-size
+  if (thumbnailData) {
+    return createImageUrlFromData(thumbnailData, imageType ?? "image/jpeg");
+  } else if (imageData) {
+    return createImageUrlFromData(imageData, imageType ?? "image/jpeg");
+  }
+
+  // fallback for standalone mode - use file path directly (works for both file:// and http://)
+  if (imageFilePath) {
+    return imageFilePath;
+  }
+
+  return null;
+}

package/src/services/indexedDBService.integration.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import "fake-indexeddb/auto";
+import { IDBFactory } from "fake-indexeddb";
+
+// each test gets a fresh idb instance to prevent data leaks
+beforeEach(() => {
+  globalThis.indexedDB = new IDBFactory();
+});
+
+// reset the db cache so setupDB re-opens after the idb reset
+vi.mock("./indexedDBService.js", async (importOriginal) => {
+  const mod = await importOriginal<typeof import("./indexedDBService.js")>();
+  return mod;
+});
+
+import {
+  resetDBCache,
+  savePlaybackPosition,
+  loadAllPlaybackPositions,
+  deletePlaybackPosition,
+  saveLastPlayed,
+  loadLastPlayed,
+  saveSetting,
+  loadSetting,
+} from "./indexedDBService.js";
+
+describe("indexedDBService integration tests", () => {
+  beforeEach(() => {
+    resetDBCache();
+  });
+
+  describe("playback positions", () => {
+    it("persists a position and reads it back", async () => {
+      await savePlaybackPosition("song-a", 55.5);
+      const positions = await loadAllPlaybackPositions();
+      expect(positions.get("song-a")).toBe(55.5);
+    });
+
+    it("overwrites an existing position", async () => {
+      await savePlaybackPosition("song-b", 10);
+      await savePlaybackPosition("song-b", 20);
+      const positions = await loadAllPlaybackPositions();
+      expect(positions.get("song-b")).toBe(20);
+    });
+
+    it("deletes a position", async () => {
+      await savePlaybackPosition("song-c", 30);
+      await deletePlaybackPosition("song-c");
+      const positions = await loadAllPlaybackPositions();
+      expect(positions.has("song-c")).toBe(false);
+    });
+
+    it("returns an empty map when no positions exist", async () => {
+      const positions = await loadAllPlaybackPositions();
+      expect(positions.size).toBe(0);
+    });
+  });
+
+  describe("last played", () => {
+    it("saves and loads the last-played song id", async () => {
+      await saveLastPlayed("pl-1", "song-xyz");
+      const result = await loadLastPlayed("pl-1");
+      expect(result).toBe("song-xyz");
+    });
+
+    it("returns null when nothing has been played", async () => {
+      const result = await loadLastPlayed("pl-none");
+      expect(result).toBeNull();
+    });
+
+    it("overwrites the previous last-played entry", async () => {
+      await saveLastPlayed("pl-1", "song-1");
+      await saveLastPlayed("pl-1", "song-2");
+      const result = await loadLastPlayed("pl-1");
+      expect(result).toBe("song-2");
+    });
+  });
+
+  describe("settings", () => {
+    it("saves and loads a string setting", async () => {
+      await saveSetting("theme", "dark");
+      const result = await loadSetting("theme");
+      expect(result).toBe("dark");
+    });
+
+    it("saves and loads a numeric setting", async () => {
+      await saveSetting("volume", 0.75);
+      const result = await loadSetting("volume");
+      expect(result).toBe(0.75);
+    });
+
+    it("returns null for an unknown setting", async () => {
+      const result = await loadSetting("nonexistent");
+      expect(result).toBeNull();
+    });
+
+    it("overwrites an existing setting", async () => {
+      await saveSetting("volume", 0.5);
+      await saveSetting("volume", 0.9);
+      const result = await loadSetting("volume");
+      expect(result).toBe(0.9);
+    });
+  });
+});

package/src/services/indexedDBService.test.ts

@@ -0,0 +1,202 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// mock idb to avoid issues with opening real IndexedDB in test env
+vi.mock("idb", () => ({
+  openDB: vi.fn(),
+}));
+
+import {
+  setupDB,
+  resetDBCache,
+  loadAllPlaybackPositions,
+  savePlaybackPosition,
+  deletePlaybackPosition,
+  saveLastPlayed,
+  loadLastPlayed,
+  saveSetting,
+  loadSetting,
+  mutateAndNotify,
+  updatePlaylist,
+  updateSong,
+  getSongsWithAudioData,
+  PLAYLISTS_STORE,
+  SONGS_STORE,
+  DB_NAME,
+} from "./indexedDBService.js";
+
+// mock BroadcastChannel
+global.BroadcastChannel = vi.fn(() => ({
+  postMessage: vi.fn(),
+  onmessage: null,
+  close: vi.fn(),
+})) as any;
+
+const mockDB = {
+  getAll: vi.fn(),
+  transaction: vi.fn(),
+  put: vi.fn(),
+  get: vi.fn(),
+  delete: vi.fn(),
+};
+
+const mockStore = {
+  put: vi.fn(),
+  get: vi.fn(),
+  delete: vi.fn(),
+  getAll: vi.fn(),
+};
+
+const mockTransaction = {
+  objectStore: vi.fn(() => mockStore),
+  done: Promise.resolve(),
+};
+
+describe("indexedDBService", () => {
+  let mockOpenDB: any;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    resetDBCache();
+
+    const { openDB } = await import("idb");
+    mockOpenDB = vi.mocked(openDB);
+    mockDB.transaction.mockReturnValue(mockTransaction);
+    mockTransaction.objectStore.mockReturnValue(mockStore);
+    mockTransaction.done = Promise.resolve();
+    mockOpenDB.mockResolvedValue(mockDB);
+    mockDB.getAll.mockResolvedValue([]);
+    mockDB.get.mockResolvedValue(undefined);
+    mockDB.put.mockResolvedValue(undefined);
+    mockDB.delete.mockResolvedValue(undefined);
+    mockStore.put.mockResolvedValue(undefined);
+    mockStore.get.mockResolvedValue(undefined);
+    mockStore.delete.mockResolvedValue(undefined);
+    mockStore.getAll.mockResolvedValue([]);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("constants", () => {
+    it("exports DB_NAME", () => {
+      expect(typeof DB_NAME).toBe("string");
+      expect(DB_NAME.length).toBeGreaterThan(0);
+    });
+
+    it("exports PLAYLISTS_STORE and SONGS_STORE as compat constants", () => {
+      expect(PLAYLISTS_STORE).toBe("playlists");
+      expect(SONGS_STORE).toBe("songs");
+    });
+  });
+
+  describe("setupDB", () => {
+    it("calls openDB to open the database", async () => {
+      await setupDB();
+      expect(mockOpenDB).toHaveBeenCalledWith(DB_NAME, 1, expect.any(Object));
+    });
+
+    it("caches the db connection on repeated calls", async () => {
+      await setupDB();
+      await setupDB();
+      // second call should reuse the cached connection, not open again
+      expect(mockOpenDB.mock.calls.length).toBe(1);
+    });
+  });
+
+  describe("resetDBCache", () => {
+    it("forces a fresh db open after reset", async () => {
+      await setupDB();
+      resetDBCache();
+      await setupDB();
+      expect(mockOpenDB.mock.calls.length).toBe(2);
+    });
+  });
+
+  describe("loadAllPlaybackPositions", () => {
+    it("returns an empty map when no positions are stored", async () => {
+      mockDB.getAll.mockResolvedValue([]);
+      const result = await loadAllPlaybackPositions();
+      expect(result).toBeInstanceOf(Map);
+      expect(result.size).toBe(0);
+    });
+
+    it("returns a map keyed by songId", async () => {
+      mockDB.getAll.mockResolvedValue([
+        { songId: "s1", position: 42, updatedAt: Date.now() },
+        { songId: "s2", position: 77, updatedAt: Date.now() },
+      ]);
+      const result = await loadAllPlaybackPositions();
+      expect(result.get("s1")).toBe(42);
+      expect(result.get("s2")).toBe(77);
+    });
+  });
+
+  describe("savePlaybackPosition", () => {
+    it("puts a record into the playbackPositions store", async () => {
+      await savePlaybackPosition("song-abc", 99.5);
+      expect(mockDB.put).toHaveBeenCalledWith(
+        "playbackPositions",
+        expect.objectContaining({ songId: "song-abc", position: 99.5 })
+      );
+    });
+  });
+
+  describe("deletePlaybackPosition", () => {
+    it("deletes a record from the playbackPositions store", async () => {
+      await deletePlaybackPosition("song-abc");
+      expect(mockDB.delete).toHaveBeenCalledWith("playbackPositions", "song-abc");
+    });
+  });
+
+  describe("saveLastPlayed / loadLastPlayed", () => {
+    it("saves and retrieves the last-played song id", async () => {
+      mockDB.get.mockResolvedValue({ playlistId: "pl-1", songId: "song-xyz" });
+      await saveLastPlayed("pl-1", "song-xyz");
+      const result = await loadLastPlayed("pl-1");
+      expect(result).toBe("song-xyz");
+    });
+
+    it("returns null when no last-played exists", async () => {
+      mockDB.get.mockResolvedValue(undefined);
+      const result = await loadLastPlayed("pl-1");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("saveSetting / loadSetting", () => {
+    it("saves and retrieves a setting value", async () => {
+      mockDB.get.mockResolvedValue({ key: "volume", value: 0.8 });
+      await saveSetting("volume", 0.8);
+      const result = await loadSetting("volume");
+      expect(result).toBe(0.8);
+    });
+
+    it("returns null for missing setting", async () => {
+      mockDB.get.mockResolvedValue(undefined);
+      const result = await loadSetting("volume");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("compat stubs (no-ops)", () => {
+    it("mutateAndNotify is a no-op that resolves without error", async () => {
+      await expect(
+        mutateAndNotify({ dbName: DB_NAME, storeName: "playlists", key: "x", updateFn: () => ({} as any) })
+      ).resolves.not.toThrow();
+    });
+
+    it("updatePlaylist is a no-op that resolves without error", async () => {
+      await expect(updatePlaylist("id", {})).resolves.not.toThrow();
+    });
+
+    it("updateSong is a no-op that resolves without error", async () => {
+      await expect(updateSong("id", {})).resolves.not.toThrow();
+    });
+
+    it("getSongsWithAudioData returns empty array", async () => {
+      const result = await getSongsWithAudioData(["s1", "s2"]);
+      expect(result).toEqual([]);
+    });
+  });
+});