taglib-wasm 0.3.3 → 0.3.9

package/index.ts

@@ -12,7 +12,7 @@
  * import { TagLib } from "taglib-wasm";
  *
  * const taglib = await TagLib.initialize();
- * const file = await taglib.openFile(audioBuffer);
+ * const file = await taglib.open(audioBuffer);
  * const tag = file.tag();
  * console.log(tag.title);
  * file.dispose();
@@ -21,12 +21,12 @@
  * @example
  * ```typescript
  * // Using the Simple API
- * import { readTags, writeTags } from "taglib-wasm";
+ * import { readTags, applyTags } from "taglib-wasm";
  *
  * const tags = await readTags("song.mp3");
  * console.log(tags.artist);
  *
- * const modified = await writeTags("song.mp3", {
+ * const modified = await applyTags("song.mp3", {
  *   artist: "New Artist",
  *   album: "New Album"
  * });
@@ -45,13 +45,67 @@ export {
   TagLib,
 } from "./src/taglib.ts";
 
+/**
+ * Error types for proper error handling and debugging.
+ * @see {@link TagLibError} - Base error class for all TagLib errors
+ * @see {@link TagLibInitializationError} - Wasm initialization failures
+ * @see {@link InvalidFormatError} - Invalid or corrupted file format
+ * @see {@link UnsupportedFormatError} - Valid but unsupported format
+ * @see {@link FileOperationError} - File read/write/save failures
+ * @see {@link MetadataError} - Tag reading/writing failures
+ * @see {@link MemoryError} - Wasm memory allocation issues
+ * @see {@link EnvironmentError} - Runtime/environment issues
+ */
+export {
+  EnvironmentError,
+  FileOperationError,
+  InvalidFormatError,
+  isEnvironmentError,
+  isFileOperationError,
+  isInvalidFormatError,
+  isMemoryError,
+  isMetadataError,
+  isTagLibError,
+  isUnsupportedFormatError,
+  MemoryError,
+  MetadataError,
+  SUPPORTED_FORMATS,
+  TagLibError,
+  TagLibInitializationError,
+  UnsupportedFormatError,
+} from "./src/errors.ts";
+
 /**
  * Simple API exports for easy tag reading and writing.
  * @see {@link readTags} - Read metadata from audio files
- * @see {@link writeTags} - Write metadata to audio files
+ * @see {@link applyTags} - Apply metadata changes and return modified buffer
+ * @see {@link updateTags} - Update metadata and save to disk
+ * @see {@link writeTags} - Deprecated alias for applyTags
  * @see {@link readProperties} - Read audio properties
+ * @see {@link readPictures} - Read cover art/pictures
+ * @see {@link applyPictures} - Apply pictures to audio files
+ * @see {@link getCoverArt} - Get primary cover art data
+ * @see {@link setCoverArt} - Set primary cover art
  */
-export { readProperties, readTags, writeTags } from "./src/simple.ts";
+export { 
+  readProperties, 
+  readTags, 
+  applyTags,
+  updateTags,
+  writeTags,  // Deprecated but exported for backward compatibility
+  readPictures,
+  applyPictures,
+  addPicture,
+  clearPictures,
+  getCoverArt,
+  setCoverArt,
+  findPictureByType,
+  replacePictureByType,
+  getPictureMetadata,
+  isValidAudioFile,
+  getFormat,
+  clearTags
+} from "./src/simple.ts";
 
 /**
  * Constants and utilities for tag name validation.
@@ -66,6 +120,41 @@ export {
   isValidTagName,
   Tags,
 } from "./src/constants.ts";
+/**
+ * File I/O utilities for cover art operations.
+ * @see {@link exportCoverArt} - Export cover art to file
+ * @see {@link importCoverArt} - Import cover art from file
+ * @see {@link copyCoverArt} - Copy cover art between files
+ */
+export {
+  exportCoverArt,
+  exportPictureByType,
+  exportAllPictures,
+  importCoverArt,
+  importPictureWithType,
+  loadPictureFromFile,
+  savePictureToFile,
+  copyCoverArt,
+  findCoverArtFiles
+} from "./src/file-utils.ts";
+
+/**
+ * Web browser utilities for cover art operations.
+ * @see {@link pictureToDataURL} - Convert picture to data URL
+ * @see {@link setCoverArtFromCanvas} - Set cover art from HTML canvas
+ * @see {@link displayPicture} - Display picture in HTML img element
+ */
+export {
+  pictureToDataURL,
+  dataURLToPicture,
+  setCoverArtFromCanvas,
+  canvasToPicture,
+  imageFileToPicture,
+  displayPicture,
+  createPictureDownloadURL,
+  createPictureGallery
+} from "./src/web-utils.ts";
+
 /**
  * Type exports for TypeScript users.
  * These types define the structure of metadata, audio properties,
@@ -83,13 +172,17 @@ export type {
   FieldMapping,
   FileType,
   Picture,
-  PictureType,
   PropertyMap,
   Tag,
   TagLibConfig,
   TagName,
 } from "./src/types.ts";
 
+/**
+ * Enum exports
+ */
+export { PictureType } from "./src/types.ts";
+
 /**
  * Wasm module types for advanced usage.
  * @see {@link TagLibModule} - Full TagLib Wasm module interface
@@ -121,7 +214,7 @@ import type { TagLibModule } from "./src/wasm.ts";
  */
 export async function loadTagLibModule(): Promise<TagLibModule> {
   // Now that we're using ES6 modules, we can use dynamic import directly
-  const { default: createTagLibModule } = await import("./build/taglib.js");
+  const { default: createTagLibModule } = await import("./build/taglib-wrapper.js");
   const module = await createTagLibModule();
   return module as TagLibModule;
 }

package/package.json

@@ -1,34 +1,56 @@
 {
   "name": "taglib-wasm",
-  "version": "0.3.3",
-  "description": "TagLib compiled to WebAssembly with TypeScript bindings for universal audio metadata handling",
+  "version": "0.3.9",
+  "description": "TagLib for TypeScript platforms: Deno, Node.js, Bun, Electron, browsers, and Cloudflare Workers",
   "main": "index.ts",
   "types": "index.ts",
   "exports": {
-    ".": "./index.ts",
-    "./workers": "./src/workers.ts",
-    "./simple": "./src/simple.ts"
+    ".": {
+      "types": "./index.ts",
+      "default": "./dist/index.js"
+    },
+    "./workers": {
+      "types": "./src/workers.ts",
+      "default": "./dist/src/workers.js"
+    },
+    "./simple": {
+      "types": "./src/simple.ts",
+      "default": "./dist/src/simple.js"
+    }
   },
   "files": [
     "index.ts",
     "src/**/*",
-    "build/taglib.wasm",
-    "build/taglib.js",
+    "dist/**/*",
     "lib/taglib/COPYING*",
-    "README.md"
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CONTRIBUTING.md"
   ],
   "scripts": {
     "build:wasm": "./build/build-wasm.sh",
-    "build:ts": "tsc",
-    "build": "npm run build:wasm && npm run build:ts",
-    "test": "deno test --allow-read tests/taglib.test.ts",
-    "test:bun": "bun test tests/taglib.test.ts",
-    "test:node": "node --loader ts-node/esm --test tests/taglib.test.ts",
-    "test:watch": "deno test --allow-read --watch tests/taglib.test.ts",
+    "build:ts": "tsc && node scripts/build-js.js",
+    "postbuild": "node scripts/postbuild.js",
+    "build": "npm run build:wasm && npm run build:ts && npm run postbuild",
+    "test": "deno test --allow-read --allow-write tests/",
+    "test:all": "deno test --allow-read --allow-write tests/index.test.ts",
+    "test:core": "deno test --allow-read --allow-write tests/taglib.test.ts",
+    "test:pictures": "deno test --allow-read --allow-write tests/picture-api.test.ts",
+    "test:edge": "deno test --allow-read --allow-write tests/edge-cases.test.ts",
+    "test:errors": "deno test --allow-read --allow-write tests/error-handling.test.ts",
+    "test:memory": "deno test --allow-read --allow-write tests/memory.test.ts",
+    "test:extended": "deno test --allow-read --allow-write tests/extended-metadata.test.ts",
+    "test:multi-runtime": "./tests/test-runtimes.sh",
+    "test:bun": "bun test tests/index.test.ts",
+    "test:node": "node --loader ts-node/esm --test tests/index.test.ts",
+    "test:watch": "deno test --allow-read --allow-write --watch tests/",
+    "test:coverage": "deno test --allow-read --allow-write --coverage=coverage tests/ && deno coverage coverage",
     "docs:dev": "cd docs && npm install && npm run dev",
     "docs:build": "cd docs && npm install && npm run build",
     "update-taglib": "./scripts/update-taglib.sh",
     "release": "./scripts/release.sh",
+    "prepublishOnly": "npm run build:ts && npm run postbuild",
     "publish:npm": "echo 'Use GitHub Actions workflow for publishing'",
     "publish:github": "echo 'Use GitHub Actions workflow for publishing'"
   },
@@ -51,12 +73,13 @@
     "browser",
     "cloudflare",
     "workers",
+    "electron",
     "replaygain",
     "musicbrainz",
     "acoustid"
   ],
-  "author": "Your Name <your.email@example.com>",
-  "license": "MIT",
+  "author": "Charles Wiltgen <cwiltgen@gmail.com>",
+  "license": "(MIT AND LGPL-2.1-or-later)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/CharlesWiltgen/taglib-wasm.git"
@@ -71,6 +94,7 @@
   "devDependencies": {
     "@types/emscripten": "^1.39.6",
     "@types/node": "^20.0.0",
+    "esbuild": "^0.25.5",
     "typescript": "^5.0.0"
   },
   "peerDependencies": {

package/src/errors.ts

@@ -0,0 +1,237 @@
+/**
+ * Custom error types for taglib-wasm with enhanced context and debugging information
+ */
+
+/**
+ * List of audio formats supported by taglib-wasm
+ */
+export const SUPPORTED_FORMATS = ['MP3', 'MP4', 'M4A', 'FLAC', 'OGG', 'WAV'] as const;
+
+/**
+ * Error codes for programmatic error handling
+ */
+export enum TagLibErrorCode {
+  INITIALIZATION_FAILED = 'INITIALIZATION_FAILED',
+  INVALID_FORMAT = 'INVALID_FORMAT',
+  UNSUPPORTED_FORMAT = 'UNSUPPORTED_FORMAT',
+  FILE_OPERATION_FAILED = 'FILE_OPERATION_FAILED',
+  METADATA_ERROR = 'METADATA_ERROR',
+  MEMORY_ERROR = 'MEMORY_ERROR',
+  ENVIRONMENT_ERROR = 'ENVIRONMENT_ERROR',
+}
+
+/**
+ * Base error class for all taglib-wasm errors
+ */
+export class TagLibError extends Error {
+  constructor(
+    message: string,
+    public readonly code: TagLibErrorCode,
+    public readonly context?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'TagLibError';
+    Object.setPrototypeOf(this, TagLibError.prototype);
+  }
+}
+
+/**
+ * Error thrown when the Wasm module fails to initialize
+ */
+export class TagLibInitializationError extends TagLibError {
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(
+      createErrorMessage('Failed to initialize TagLib Wasm module', message),
+      TagLibErrorCode.INITIALIZATION_FAILED,
+      context
+    );
+    this.name = 'TagLibInitializationError';
+    Object.setPrototypeOf(this, TagLibInitializationError.prototype);
+  }
+}
+
+/**
+ * Error thrown when an audio file format is invalid or corrupted
+ */
+export class InvalidFormatError extends TagLibError {
+  constructor(
+    message: string,
+    public readonly bufferSize?: number,
+    context?: Record<string, unknown>
+  ) {
+    const details = [`Invalid audio file format: ${message}`];
+    
+    if (bufferSize !== undefined) {
+      details.push(`Buffer size: ${formatFileSize(bufferSize)}`);
+      if (bufferSize < 1024) {
+        details.push('Audio files must be at least 1KB to contain valid headers.');
+      }
+    }
+    
+    super(
+      details.join('. '),
+      TagLibErrorCode.INVALID_FORMAT,
+      { ...context, bufferSize }
+    );
+    this.name = 'InvalidFormatError';
+    Object.setPrototypeOf(this, InvalidFormatError.prototype);
+  }
+}
+
+/**
+ * Error thrown when an audio format is recognized but not supported
+ */
+export class UnsupportedFormatError extends TagLibError {
+  constructor(
+    public readonly format: string,
+    public readonly supportedFormats: readonly string[] = SUPPORTED_FORMATS,
+    context?: Record<string, unknown>
+  ) {
+    super(
+      `Unsupported audio format: ${format}. Supported formats: ${supportedFormats.join(', ')}`,
+      TagLibErrorCode.UNSUPPORTED_FORMAT,
+      { ...context, format, supportedFormats }
+    );
+    this.name = 'UnsupportedFormatError';
+    Object.setPrototypeOf(this, UnsupportedFormatError.prototype);
+  }
+}
+
+/**
+ * Error thrown during file operations (read, write, save)
+ */
+export class FileOperationError extends TagLibError {
+  constructor(
+    public readonly operation: 'read' | 'write' | 'save',
+    message: string,
+    public readonly path?: string,
+    context?: Record<string, unknown>
+  ) {
+    const details = [`Failed to ${operation} file`];
+    if (path) {
+      details.push(`Path: ${path}`);
+    }
+    details.push(message);
+    
+    super(
+      details.join('. '),
+      TagLibErrorCode.FILE_OPERATION_FAILED,
+      { ...context, operation, path }
+    );
+    this.name = 'FileOperationError';
+    Object.setPrototypeOf(this, FileOperationError.prototype);
+  }
+}
+
+/**
+ * Error thrown when metadata operations fail
+ */
+export class MetadataError extends TagLibError {
+  constructor(
+    public readonly operation: 'read' | 'write',
+    message: string,
+    public readonly field?: string,
+    context?: Record<string, unknown>
+  ) {
+    const details = [`Failed to ${operation} metadata`];
+    if (field) {
+      details.push(`Field: ${field}`);
+    }
+    details.push(message);
+    
+    super(
+      details.join('. '),
+      TagLibErrorCode.METADATA_ERROR,
+      { ...context, operation, field }
+    );
+    this.name = 'MetadataError';
+    Object.setPrototypeOf(this, MetadataError.prototype);
+  }
+}
+
+/**
+ * Error thrown when Wasm memory operations fail
+ */
+export class MemoryError extends TagLibError {
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(
+      createErrorMessage('Memory allocation failed', message),
+      TagLibErrorCode.MEMORY_ERROR,
+      context
+    );
+    this.name = 'MemoryError';
+    Object.setPrototypeOf(this, MemoryError.prototype);
+  }
+}
+
+/**
+ * Error thrown when the environment doesn't support required features
+ */
+export class EnvironmentError extends TagLibError {
+  constructor(
+    public readonly environment: string,
+    message: string,
+    public readonly requiredFeature?: string,
+    context?: Record<string, unknown>
+  ) {
+    const details = [`Environment '${environment}' ${message}`];
+    if (requiredFeature) {
+      details.push(`Required feature: ${requiredFeature}`);
+    }
+    
+    super(
+      details.join('. '),
+      TagLibErrorCode.ENVIRONMENT_ERROR,
+      { ...context, environment, requiredFeature }
+    );
+    this.name = 'EnvironmentError';
+    Object.setPrototypeOf(this, EnvironmentError.prototype);
+  }
+}
+
+/**
+ * Helper function to create consistent error messages
+ */
+function createErrorMessage(prefix: string, details: string): string {
+  return `${prefix}: ${details}`;
+}
+
+/**
+ * Format file size in human-readable format
+ */
+function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} bytes`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Type guards for error handling
+ */
+export function isTagLibError(error: unknown): error is TagLibError {
+  return error instanceof TagLibError;
+}
+
+export function isInvalidFormatError(error: unknown): error is InvalidFormatError {
+  return error instanceof InvalidFormatError;
+}
+
+export function isUnsupportedFormatError(error: unknown): error is UnsupportedFormatError {
+  return error instanceof UnsupportedFormatError;
+}
+
+export function isFileOperationError(error: unknown): error is FileOperationError {
+  return error instanceof FileOperationError;
+}
+
+export function isMetadataError(error: unknown): error is MetadataError {
+  return error instanceof MetadataError;
+}
+
+export function isMemoryError(error: unknown): error is MemoryError {
+  return error instanceof MemoryError;
+}
+
+export function isEnvironmentError(error: unknown): error is EnvironmentError {
+  return error instanceof EnvironmentError;
+}