@freqhole/playlistz 0.0.1

package/src/utils/hashUtils.ts

@@ -0,0 +1,41 @@
+/**
+ * Utility functions for calculating SHA-256 hashes
+ */
+
+/**
+ * Calculate SHA-256 hash of ArrayBuffer data
+ * @param data ArrayBuffer containing the data to hash
+ * @returns Promise<string> Hex string representation of the hash
+ */
+export async function calculateSHA256(data: ArrayBuffer): Promise<string> {
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hashHex = hashArray
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  return hashHex;
+}
+
+/**
+ * Calculate SHA-256 hash of a File
+ * @param file File to hash
+ * @returns Promise<string> Hex string representation of the hash
+ */
+export async function calculateFileSHA256(file: File): Promise<string> {
+  const arrayBuffer = await file.arrayBuffer();
+  return calculateSHA256(arrayBuffer);
+}
+
+/**
+ * Verify if a given hash matches the SHA-256 of the provided data
+ * @param data ArrayBuffer containing the data to verify
+ * @param expectedHash Expected SHA-256 hash as hex string
+ * @returns Promise<boolean> True if hash matches, false otherwise
+ */
+export async function verifySHA256(
+  data: ArrayBuffer,
+  expectedHash: string
+): Promise<boolean> {
+  const actualHash = await calculateSHA256(data);
+  return actualHash === expectedHash;
+}

package/src/utils/log.ts

@@ -0,0 +1,97 @@
+// lightweight logger with level + tag filtering.
+// level order: trace < debug < info < warn < error
+//
+// build-time config (vite env vars):
+//   VITE_LOG_LEVEL  - "trace" | "debug" | "info" | "warn" | "error"
+//                     default: "debug" in dev, "warn" in prod
+//   VITE_LOG_FILTER - comma-separated tag prefixes, e.g. "p2p,audio"  (default: all tags)
+//
+// runtime override via devtools (no rebuild needed):
+//   localStorage.logLevel = "trace";
+//   localStorage.logFilter = "automerge.repo,idb.docindex";
+//   location.reload();
+//
+// trace is off by default even in dev - enable it explicitly when needed.
+// it's useful for detailed call-by-call tracing of services without adding
+// noise to normal debug output.
+//
+// tags use dotted namespaces, e.g. "p2p.transfer", "audio.player", "idb.service".
+// filter prefix matching: "p2p" matches "p2p", "p2p.transfer", "p2p.knock", etc.
+//
+// usage:
+//   import { log } from "../utils/log.js";
+//   log.warn("share.panel", "could not build share link:", err);
+//   log.debug("playlist.sync", "syncPlaylists #", syncId, "entries:", entries.length);
+//   log.trace("automerge.repo", "findPlaylistDoc call #", n, docId);
+
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+
+const LEVEL_NUM: Record<LogLevel, number> = {
+  trace: -1,
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+function resolveLevel(): number {
+  const override =
+    typeof localStorage !== "undefined" && typeof localStorage.getItem === "function"
+      ? (localStorage.getItem("logLevel") as LogLevel | null)
+      : null;
+  // VITE_LOG_LEVEL is injected at build time; fall back to debug in dev, warn in prod
+  const env = import.meta.env.VITE_LOG_LEVEL as LogLevel | undefined;
+  // trace is never on by default - must be explicitly requested
+  const raw = override ?? env ?? (import.meta.env.DEV ? "debug" : "warn");
+  return LEVEL_NUM[raw as LogLevel] ?? LEVEL_NUM.warn;
+}
+
+function resolveFilter(): string[] {
+  const override =
+    typeof localStorage !== "undefined" && typeof localStorage.getItem === "function"
+      ? localStorage.getItem("logFilter")
+      : null;
+  const env = import.meta.env.VITE_LOG_FILTER as string | undefined;
+  const raw = override ?? env ?? "";
+  return raw
+    ? raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+}
+
+function allowed(tag: string): boolean {
+  const filter = resolveFilter();
+  if (filter.length === 0) return true;
+  return filter.some(
+    (prefix) => tag === prefix || tag.startsWith(prefix + ".")
+  );
+}
+
+function emit(
+  level: LogLevel,
+  tag: string,
+  msg: string,
+  ...args: unknown[]
+): void {
+  if (LEVEL_NUM[level] < resolveLevel()) return;
+  if (!allowed(tag)) return;
+  const prefix = `[${tag}]`;
+  if (level === "error") console.error(prefix, msg, ...args);
+  else if (level === "warn") console.warn(prefix, msg, ...args);
+  else console.log(prefix, msg, ...args);
+}
+
+export const log = {
+  trace: (tag: string, msg: string, ...args: unknown[]): void =>
+    emit("trace", tag, msg, ...args),
+  debug: (tag: string, msg: string, ...args: unknown[]): void =>
+    emit("debug", tag, msg, ...args),
+  info: (tag: string, msg: string, ...args: unknown[]): void =>
+    emit("info", tag, msg, ...args),
+  warn: (tag: string, msg: string, ...args: unknown[]): void =>
+    emit("warn", tag, msg, ...args),
+  error: (tag: string, msg: string, ...args: unknown[]): void =>
+    emit("error", tag, msg, ...args),
+};

package/src/utils/m3u.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect } from "vitest";
+import { parseM3U, serializeM3U, generateM3UContent } from "./m3u.js";
+import type { Playlist, Song } from "../types/playlist.js";
+
+// ---- helpers ----
+
+const BASIC_M3U = `#EXTM3U
+# Playlist: test mix
+# Description: some songs
+# PlaylistImage: data/playlist-cover.jpg
+
+#EXTINF:180, artist a - song one
+# Title: song one
+# Artist: artist a
+# Album: album x
+# Image: data/01-song one-cover.jpg
+data/01-song one.mp3
+
+#EXTINF:240, artist b - song two
+# Title: song two
+# Artist: artist b
+# Album: album y
+data/02-song two.m4a
+`;
+
+// ---- parseM3U ----
+
+describe("parseM3U", () => {
+  it("parses playlist header fields", () => {
+    const p = parseM3U(BASIC_M3U);
+    expect(p.title).toBe("test mix");
+    expect(p.description).toBe("some songs");
+    expect(p.playlistImageFile).toBe("data/playlist-cover.jpg");
+  });
+
+  it("id and rev are null when absent", () => {
+    const p = parseM3U(BASIC_M3U);
+    expect(p.id).toBeNull();
+    expect(p.rev).toBeNull();
+  });
+
+  it("parses PlaylistId and PlaylistRev when present", () => {
+    const src = `#EXTM3U\n# Playlist: x\n# PlaylistId: abc-123\n# PlaylistRev: 7\n`;
+    const p = parseM3U(src);
+    expect(p.id).toBe("abc-123");
+    expect(p.rev).toBe(7);
+  });
+
+  it("parses song count correctly", () => {
+    expect(parseM3U(BASIC_M3U).songs).toHaveLength(2);
+  });
+
+  it("parses first song fields", () => {
+    const s = parseM3U(BASIC_M3U).songs[0]!;
+    expect(s.title).toBe("song one");
+    expect(s.artist).toBe("artist a");
+    expect(s.album).toBe("album x");
+    expect(s.duration).toBe(180);
+    expect(s.audioFile).toBe("data/01-song one.mp3");
+    expect(s.imageFile).toBe("data/01-song one-cover.jpg");
+  });
+
+  it("parses song with no image as empty imageFile", () => {
+    const s = parseM3U(BASIC_M3U).songs[1]!;
+    expect(s.imageFile).toBe("");
+  });
+
+  it("preserves rawLines for write-back", () => {
+    const p = parseM3U(BASIC_M3U);
+    expect(p.rawLines.length).toBeGreaterThan(0);
+    expect(p.rawLines[0]).toBe("#EXTM3U");
+  });
+
+  it("parses empty string without throwing", () => {
+    const p = parseM3U("");
+    expect(p.songs).toHaveLength(0);
+    expect(p.title).toBe("");
+  });
+});
+
+// ---- serializeM3U ----
+
+describe("serializeM3U", () => {
+  it("inserts PlaylistId and PlaylistRev when absent", () => {
+    const p = parseM3U(BASIC_M3U);
+    p.id = "new-id";
+    p.rev = 0;
+    const out = serializeM3U(p);
+    expect(out).toContain("# PlaylistId: new-id");
+    expect(out).toContain("# PlaylistRev: 0");
+  });
+
+  it("updates existing PlaylistId in place", () => {
+    const src = `#EXTM3U\n# Playlist: x\n# PlaylistId: old-id\n# PlaylistRev: 1\n`;
+    const p = parseM3U(src);
+    p.id = "updated-id";
+    p.rev = 2;
+    const out = serializeM3U(p);
+    expect(out).toContain("# PlaylistId: updated-id");
+    expect(out).not.toContain("# PlaylistId: old-id");
+    expect(out).toContain("# PlaylistRev: 2");
+    // should not duplicate
+    expect(out.split("# PlaylistId:").length - 1).toBe(1);
+  });
+
+  it("round-trips all songs unchanged", () => {
+    const p = parseM3U(BASIC_M3U);
+    p.id = "x";
+    p.rev = 0;
+    const out = serializeM3U(p);
+    expect(out).toContain("data/01-song one.mp3");
+    expect(out).toContain("data/02-song two.m4a");
+  });
+});
+
+// ---- generateM3UContent ----
+
+describe("generateM3UContent", () => {
+  const getExt = (mime: string) => {
+    const map: Record<string, string> = { "image/jpeg": ".jpg", "image/png": ".png", "image/gif": ".gif", "image/webp": ".webp" };
+    return map[mime] ?? ".jpg";
+  };
+
+  const playlist = {
+    id: "pl-1",
+    title: "my playlist",
+    description: "cool songs",
+    rev: 3,
+    imageData: new ArrayBuffer(1),
+    imageType: "image/jpeg",
+  } as unknown as Playlist;
+
+  const songs = [
+    {
+      title: "tune",
+      artist: "dj",
+      album: "ep",
+      duration: 120,
+      originalFilename: "01-tune.mp3",
+      imageData: new ArrayBuffer(1),
+      imageType: "image/jpeg",
+    } as unknown as Song,
+  ];
+
+  it("starts with #EXTM3U", () => {
+    const out = generateM3UContent(playlist, songs, ["01-tune.mp3"], getExt);
+    expect(out).toMatch(/^#EXTM3U\n/);
+  });
+
+  it("includes PlaylistId and PlaylistRev", () => {
+    const out = generateM3UContent(playlist, songs, ["01-tune.mp3"], getExt);
+    expect(out).toContain("# PlaylistId: pl-1");
+    expect(out).toContain("# PlaylistRev: 3");
+  });
+
+  it("includes playlist title and description", () => {
+    const out = generateM3UContent(playlist, songs, ["01-tune.mp3"], getExt);
+    expect(out).toContain("# Playlist: my playlist");
+    expect(out).toContain("# Description: cool songs");
+  });
+
+  it("includes EXTINF with correct duration and audio path", () => {
+    const out = generateM3UContent(playlist, songs, ["01-tune.mp3"], getExt);
+    expect(out).toContain("#EXTINF:120, dj - tune");
+    expect(out).toContain("data/01-tune.mp3");
+  });
+
+  it("skips songs with no filename", () => {
+    const out = generateM3UContent(playlist, songs, [undefined as unknown as string], getExt);
+    expect(out).not.toContain("#EXTINF");
+  });
+});

package/src/utils/m3u.ts

@@ -0,0 +1,136 @@
+// shared m3u8 format utilities: parser + generator.
+// browser-compatible and node-compatible (no fs/path imports).
+
+import type { Playlist, Song } from "../types/playlist.js";
+
+// ---- types ----
+
+export interface M3USong {
+  duration: number;
+  title: string;
+  artist: string;
+  album: string;
+  imageFile: string;   // e.g. "data/01-song-cover.jpg" as written in m3u8
+  audioFile: string;   // e.g. "data/01-song.mp3" as written in m3u8
+}
+
+export interface M3UPlaylist {
+  title: string;
+  description: string;
+  playlistImageFile: string;  // e.g. "data/playlist-cover.jpg"
+  id: string | null;
+  rev: number | null;
+  songs: M3USong[];
+  rawLines: string[];         // original lines, preserved for write-back
+}
+
+// ---- parser ----
+
+export function parseM3U(content: string): M3UPlaylist {
+  const lines = content.split("\n");
+  const result: M3UPlaylist = {
+    title: "",
+    description: "",
+    playlistImageFile: "",
+    id: null,
+    rev: null,
+    songs: [],
+    rawLines: lines,
+  };
+
+  let pendingExtinf: { duration: number } | null = null;
+  let pendingTitle = "";
+  let pendingArtist = "";
+  let pendingAlbum = "";
+  let pendingImage = "";
+
+  for (const line of lines) {
+    const t = line.trim();
+
+    if (t.startsWith("# Playlist:"))       result.title             = t.slice("# Playlist:".length).trim();
+    else if (t.startsWith("# Description:"))result.description       = t.slice("# Description:".length).trim();
+    else if (t.startsWith("# PlaylistImage:"))result.playlistImageFile = t.slice("# PlaylistImage:".length).trim();
+    else if (t.startsWith("# PlaylistId:")) result.id                = t.slice("# PlaylistId:".length).trim();
+    else if (t.startsWith("# PlaylistRev:"))result.rev               = parseInt(t.slice("# PlaylistRev:".length).trim(), 10);
+    else if (t.startsWith("#EXTINF:")) {
+      const durationStr = t.slice("#EXTINF:".length).split(",")[0] ?? "0";
+      pendingExtinf = { duration: parseInt(durationStr, 10) };
+      pendingTitle = pendingArtist = pendingAlbum = pendingImage = "";
+    } else if (t.startsWith("# Title:"))   pendingTitle  = t.slice("# Title:".length).trim();
+    else if (t.startsWith("# Artist:"))    pendingArtist = t.slice("# Artist:".length).trim();
+    else if (t.startsWith("# Album:"))     pendingAlbum  = t.slice("# Album:".length).trim();
+    else if (t.startsWith("# Image:"))     pendingImage  = t.slice("# Image:".length).trim();
+    else if (t && !t.startsWith("#") && pendingExtinf) {
+      result.songs.push({
+        duration: pendingExtinf.duration,
+        title: pendingTitle,
+        artist: pendingArtist,
+        album: pendingAlbum,
+        imageFile: pendingImage,
+        audioFile: t,
+      });
+      pendingExtinf = null;
+    }
+  }
+
+  return result;
+}
+
+// ---- write-back: insert/update PlaylistId + PlaylistRev in raw lines ----
+
+export function serializeM3U(parsed: M3UPlaylist): string {
+  const lines = [...parsed.rawLines];
+
+  const upsertAfter = (marker: string, tag: string, value: string) => {
+    const existing = lines.findIndex((l) => l.trim().startsWith(tag));
+    if (existing >= 0) {
+      lines[existing] = `${tag} ${value}`;
+    } else {
+      const after = lines.findIndex((l) => l.trim().startsWith(marker));
+      if (after >= 0) lines.splice(after + 1, 0, `${tag} ${value}`);
+    }
+  };
+
+  upsertAfter("# Playlist:", "# PlaylistId:", parsed.id ?? "");
+  upsertAfter("# PlaylistId:", "# PlaylistRev:", String(parsed.rev ?? 0));
+
+  return lines.join("\n");
+}
+
+// ---- generator (used by playlistDownloadService) ----
+
+export function generateM3UContent(
+  playlist: Playlist,
+  songs: Song[],
+  fileNames: string[],
+  getFileExtension: (mimeType: string) => string
+): string {
+  let out = "#EXTM3U\n";
+  out += `# Playlist: ${playlist.title}\n`;
+  if (playlist.id)    out += `# PlaylistId: ${playlist.id}\n`;
+  out += `# PlaylistRev: ${playlist.rev ?? 0}\n`;
+  if (playlist.description) out += `# Description: ${playlist.description}\n`;
+  if (playlist.imageData) {
+    const ext = getFileExtension(playlist.imageType ?? "image/jpeg");
+    out += `# PlaylistImage: data/playlist-cover${ext}\n`;
+  }
+  out += "\n";
+
+  songs.forEach((song, i) => {
+    const fileName = fileNames[i];
+    if (!fileName) return;
+    const duration = Math.round(song.duration ?? 0);
+    out += `#EXTINF:${duration}, ${song.artist} - ${song.title}\n`;
+    out += `# Title: ${song.title}\n`;
+    out += `# Artist: ${song.artist}\n`;
+    out += `# Album: ${song.album}\n`;
+    if (song.imageData && song.originalFilename) {
+      const baseName = song.originalFilename.replace(/\.[^.]+$/, "");
+      const ext = getFileExtension(song.imageType ?? "image/jpeg");
+      out += `# Image: data/${baseName}-cover${ext}\n`;
+    }
+    out += `data/${fileName}\n\n`;
+  });
+
+  return out;
+}

package/src/utils/mockData.ts

@@ -0,0 +1,166 @@
+// test utilities for creating properly typed mock data
+
+import type { Playlist, Song } from "../types/playlist.js";
+import type { StandaloneData } from "../services/standaloneService.js";
+import type { FreqholePlaylistSong as StandaloneSongData } from "../utils/standaloneTemplates.js";
+
+// create a minimal but valid song object for testing
+export function createMockSong(overrides: Partial<Song> = {}): Song {
+  const now = Date.now();
+  return {
+    id: "test-song-id",
+    mimeType: "audio/mp3",
+    originalFilename: "test-song.mp3",
+    title: "Test Song",
+    artist: "Test Artist",
+    album: "Test Album",
+    duration: 180,
+    position: 0,
+    createdAt: now,
+    updatedAt: now,
+    playlistId: "test-playlist-id",
+    ...overrides,
+  };
+}
+
+// create a minimal but valid playlist object for testing
+export function createMockPlaylist(
+  overrides: Partial<Playlist> = {}
+): Playlist {
+  const now = Date.now();
+  return {
+    id: "test-playlist-id",
+    title: "Test Playlist",
+    songIds: [],
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+// create a song with audio data for testing
+export function createMockSongWithAudio(overrides: Partial<Song> = {}): Song {
+  const audioData = new ArrayBuffer(1024); // mock audio data
+  return createMockSong({
+    audioData,
+    fileSize: audioData.byteLength,
+    ...overrides,
+  });
+}
+
+// create a song with image data for testing
+export function createMockSongWithImage(overrides: Partial<Song> = {}): Song {
+  const imageData = new ArrayBuffer(2048); // mock image data
+  const thumbnailData = new ArrayBuffer(512); // mock thumbnail data
+  return createMockSong({
+    imageData,
+    thumbnailData,
+    imageType: "image/jpeg",
+    ...overrides,
+  });
+}
+
+// create a playlist with image data for testing
+export function createMockPlaylistWithImage(
+  overrides: Partial<Playlist> = {}
+): Playlist {
+  const imageData = new ArrayBuffer(2048);
+  const thumbnailData = new ArrayBuffer(512);
+  return createMockPlaylist({
+    imageData,
+    thumbnailData,
+    imageType: "image/jpeg",
+    ...overrides,
+  });
+}
+
+// create mock standalone song data
+export function createMockStandaloneSongData(
+  overrides: Partial<StandaloneSongData> = {}
+): StandaloneSongData {
+  return {
+    id: "test-song-id",
+    title: "Test Song",
+    artist: "Test Artist",
+    album: "Test Album",
+    duration: 180,
+    originalFilename: "test-song.mp3",
+    fileSize: 1024,
+    sha: "mock-sha-hash",
+    ...overrides,
+  };
+}
+
+// create mock standalone data
+export function createMockStandaloneData(
+  overrides: Partial<StandaloneData> = {}
+): StandaloneData {
+  return {
+    playlist: {
+      id: "test-playlist-id",
+      title: "test playlist",
+      description: "test description",
+      rev: 1,
+    },
+    songs: [createMockStandaloneSongData()],
+    ...overrides,
+  };
+}
+
+// create a complete playlist with songs for testing
+export function createMockPlaylistWithSongs(songCount = 3): {
+  playlist: Playlist;
+  songs: Song[];
+} {
+  const songs = Array.from({ length: songCount }, (_, i) =>
+    createMockSong({
+      id: `song-${i}`,
+      title: `song ${i + 1}`,
+      position: i,
+    })
+  );
+
+  const playlist = createMockPlaylist({
+    songIds: songs.map((song) => song.id),
+  });
+
+  return { playlist, songs };
+}
+
+// helper to create arraybuffer with specific content for testing
+export function createMockArrayBuffer(
+  size: number,
+  fillByte = 42
+): ArrayBuffer {
+  const buffer = new ArrayBuffer(size);
+  const view = new Uint8Array(buffer);
+  view.fill(fillByte);
+  return buffer;
+}
+
+// mock file object for upload tests
+export function createMockFile(
+  name = "test.mp3",
+  type = "audio/mp3",
+  size = 1024
+): File {
+  const content = new ArrayBuffer(size);
+  return new File([content], name, { type });
+}
+
+// create minimal objects for testing (when full objects aren't needed)
+export const mockIds = {
+  playlist: "test-playlist-id",
+  song: "test-song-id",
+  user: "test-user-id",
+} as const;
+
+// common test data
+export const mockTimestamp = 1640995200000; // fixed timestamp for consistent tests
+export const mockSha =
+  "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+export const mockMimeTypes = {
+  audio: "audio/mp3",
+  image: "image/jpeg",
+  video: "video/mp4",
+} as const;