taglib-wasm 0.3.3 → 0.3.9

package/dist/src/constants.ts

@@ -0,0 +1,227 @@
+/**
+ * Standard tag property names used by TagLib.
+ * These constants provide type-safe access to tag properties with IDE autocomplete.
+ *
+ * @example
+ * ```typescript
+ * import { Tags } from 'taglib-wasm';
+ *
+ * // Read tags
+ * const title = file.tag.properties.get(Tags.Title);
+ * const artist = file.tag.properties.get(Tags.Artist);
+ *
+ * // Write tags
+ * file.tag.properties.set(Tags.Album, "Dark Side of the Moon");
+ * file.tag.properties.set(Tags.Year, "1973");
+ * ```
+ */
+export const Tags = {
+  // Basic Properties
+  /** Track/song title */
+  Title: "TITLE",
+  /** Primary performer(s) */
+  Artist: "ARTIST",
+  /** Album/collection name */
+  Album: "ALBUM",
+  /** Date of recording (year) */
+  Date: "DATE",
+  /** Track number on album */
+  TrackNumber: "TRACKNUMBER",
+  /** Musical genre */
+  Genre: "GENRE",
+  /** Comments/notes */
+  Comment: "COMMENT",
+
+  // Extended Properties
+  /** Band/orchestra/ensemble */
+  AlbumArtist: "ALBUMARTIST",
+  /** Original composer(s) */
+  Composer: "COMPOSER",
+  /** Copyright information */
+  Copyright: "COPYRIGHT",
+  /** Encoding software/person */
+  EncodedBy: "ENCODEDBY",
+  /** Disc number for multi-disc sets */
+  DiscNumber: "DISCNUMBER",
+  /** Beats per minute */
+  Bpm: "BPM",
+  /** Lyrics/text writer(s) */
+  Lyricist: "LYRICIST",
+  /** Conductor */
+  Conductor: "CONDUCTOR",
+  /** Person who remixed */
+  Remixer: "REMIXEDBY",
+  /** Language of vocals/lyrics */
+  Language: "LANGUAGE",
+  /** Publisher */
+  Publisher: "PUBLISHER",
+  /** Mood/atmosphere */
+  Mood: "MOOD",
+  /** Media type (CD, vinyl, etc.) */
+  Media: "MEDIA",
+  /** Radio station owner */
+  RadioStationOwner: "RADIOSTATIONOWNER",
+  /** Producer */
+  Producer: "PRODUCER",
+  /** Album subtitle */
+  Subtitle: "SUBTITLE",
+  /** Release label */
+  Label: "LABEL",
+
+  // Sorting Properties
+  /** Sort name for title */
+  TitleSort: "TITLESORT",
+  /** Sort name for artist */
+  ArtistSort: "ARTISTSORT",
+  /** Sort name for album artist */
+  AlbumArtistSort: "ALBUMARTISTSORT",
+  /** Sort name for album */
+  AlbumSort: "ALBUMSORT",
+  /** Sort name for composer */
+  ComposerSort: "COMPOSERSORT",
+
+  // Identifiers
+  /** International Standard Recording Code */
+  Isrc: "ISRC",
+  /** Amazon Standard Identification Number */
+  Asin: "ASIN",
+  /** Catalog number */
+  CatalogNumber: "CATALOGNUMBER",
+  /** Barcode (EAN/UPC) */
+  Barcode: "BARCODE",
+
+  // MusicBrainz Identifiers
+  /** MusicBrainz Artist ID */
+  MusicBrainzArtistId: "MUSICBRAINZ_ARTISTID",
+  /** MusicBrainz Release Artist ID */
+  MusicBrainzReleaseArtistId: "MUSICBRAINZ_ALBUMARTISTID",
+  /** MusicBrainz Work ID */
+  MusicBrainzWorkId: "MUSICBRAINZ_WORKID",
+  /** MusicBrainz Release ID */
+  MusicBrainzReleaseId: "MUSICBRAINZ_ALBUMID",
+  /** MusicBrainz Recording ID */
+  MusicBrainzRecordingId: "MUSICBRAINZ_TRACKID",
+  /** MusicBrainz Track ID (deprecated, use RecordingId) */
+  MusicBrainzTrackId: "MUSICBRAINZ_TRACKID",
+  /** MusicBrainz Release Group ID */
+  MusicBrainzReleaseGroupId: "MUSICBRAINZ_RELEASEGROUPID",
+  /** MusicBrainz Release Track ID */
+  MusicBrainzReleaseTrackId: "MUSICBRAINZ_RELEASETRACKID",
+
+  // Podcast Properties
+  /** Podcast identifier */
+  PodcastId: "PODCASTID",
+  /** Podcast URL */
+  PodcastUrl: "PODCASTURL",
+
+  // Grouping and Work
+  /** Content group/work */
+  Grouping: "GROUPING",
+  /** Work name */
+  Work: "WORK",
+
+  // Additional Metadata
+  /** Lyrics content */
+  Lyrics: "LYRICS",
+  /** Album gain (ReplayGain) */
+  AlbumGain: "REPLAYGAIN_ALBUM_GAIN",
+  /** Album peak (ReplayGain) */
+  AlbumPeak: "REPLAYGAIN_ALBUM_PEAK",
+  /** Track gain (ReplayGain) */
+  TrackGain: "REPLAYGAIN_TRACK_GAIN",
+  /** Track peak (ReplayGain) */
+  TrackPeak: "REPLAYGAIN_TRACK_PEAK",
+
+  // Special handling
+  /** Original artist for covers */
+  OriginalArtist: "ORIGINALARTIST",
+  /** Original album */
+  OriginalAlbum: "ORIGINALALBUM",
+  /** Original release date */
+  OriginalDate: "ORIGINALDATE",
+  /** Script/writing system */
+  Script: "SCRIPT",
+  /** Involved people list */
+  InvolvedPeopleList: "INVOLVEDPEOPLELIST",
+
+  // Technical Properties
+  /** Encoder settings/software */
+  EncoderSettings: "ENCODERSETTINGS",
+  /** Source media */
+  SourceMedia: "SOURCEMEDIA",
+} as const;
+
+/**
+ * Type representing all valid tag property names
+ */
+export type TagName = typeof Tags[keyof typeof Tags];
+
+/**
+ * Type guard to check if a string is a valid tag name
+ */
+export function isValidTagName(name: string): name is TagName {
+  return Object.values(Tags).includes(name as TagName);
+}
+
+/**
+ * Get all available tag names as an array
+ */
+export function getAllTagNames(): readonly TagName[] {
+  return Object.values(Tags);
+}
+
+/**
+ * Format-specific tag mappings (for reference only - TagLib handles these automatically)
+ * This shows how standard property names map to format-specific identifiers.
+ */
+export const FormatMappings = {
+  Title: {
+    id3v2: "TIT2",
+    mp4: "©nam",
+    vorbis: "TITLE",
+    ape: "Title",
+    riff: "INAM",
+  },
+  Artist: {
+    id3v2: "TPE1",
+    mp4: "©ART",
+    vorbis: "ARTIST",
+    ape: "Artist",
+    riff: "IART",
+  },
+  Album: {
+    id3v2: "TALB",
+    mp4: "©alb",
+    vorbis: "ALBUM",
+    ape: "Album",
+    riff: "IPRD",
+  },
+  Date: {
+    id3v2: "TDRC",
+    mp4: "©day",
+    vorbis: "DATE",
+    ape: "Year",
+    riff: "ICRD",
+  },
+  Genre: {
+    id3v2: "TCON",
+    mp4: "©gen",
+    vorbis: "GENRE",
+    ape: "Genre",
+    riff: "IGNR",
+  },
+  Comment: {
+    id3v2: "COMM",
+    mp4: "©cmt",
+    vorbis: "COMMENT",
+    ape: "Comment",
+    riff: "ICMT",
+  },
+  TrackNumber: {
+    id3v2: "TRCK",
+    mp4: "trkn",
+    vorbis: "TRACKNUMBER",
+    ape: "Track",
+    riff: "ITRK",
+  },
+} as const;

package/dist/src/errors.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Custom error types for taglib-wasm with enhanced context and debugging information
+ */
+/**
+ * List of audio formats supported by taglib-wasm
+ */
+export declare const SUPPORTED_FORMATS: readonly ["MP3", "MP4", "M4A", "FLAC", "OGG", "WAV"];
+/**
+ * Error codes for programmatic error handling
+ */
+export declare 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 declare class TagLibError extends Error {
+    readonly code: TagLibErrorCode;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: TagLibErrorCode, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Error thrown when the Wasm module fails to initialize
+ */
+export declare class TagLibInitializationError extends TagLibError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when an audio file format is invalid or corrupted
+ */
+export declare class InvalidFormatError extends TagLibError {
+    readonly bufferSize?: number | undefined;
+    constructor(message: string, bufferSize?: number | undefined, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when an audio format is recognized but not supported
+ */
+export declare class UnsupportedFormatError extends TagLibError {
+    readonly format: string;
+    readonly supportedFormats: readonly string[];
+    constructor(format: string, supportedFormats?: readonly string[], context?: Record<string, unknown>);
+}
+/**
+ * Error thrown during file operations (read, write, save)
+ */
+export declare class FileOperationError extends TagLibError {
+    readonly operation: 'read' | 'write' | 'save';
+    readonly path?: string | undefined;
+    constructor(operation: 'read' | 'write' | 'save', message: string, path?: string | undefined, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when metadata operations fail
+ */
+export declare class MetadataError extends TagLibError {
+    readonly operation: 'read' | 'write';
+    readonly field?: string | undefined;
+    constructor(operation: 'read' | 'write', message: string, field?: string | undefined, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when Wasm memory operations fail
+ */
+export declare class MemoryError extends TagLibError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when the environment doesn't support required features
+ */
+export declare class EnvironmentError extends TagLibError {
+    readonly environment: string;
+    readonly requiredFeature?: string | undefined;
+    constructor(environment: string, message: string, requiredFeature?: string | undefined, context?: Record<string, unknown>);
+}
+/**
+ * Type guards for error handling
+ */
+export declare function isTagLibError(error: unknown): error is TagLibError;
+export declare function isInvalidFormatError(error: unknown): error is InvalidFormatError;
+export declare function isUnsupportedFormatError(error: unknown): error is UnsupportedFormatError;
+export declare function isFileOperationError(error: unknown): error is FileOperationError;
+export declare function isMetadataError(error: unknown): error is MetadataError;
+export declare function isMemoryError(error: unknown): error is MemoryError;
+export declare function isEnvironmentError(error: unknown): error is EnvironmentError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/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;
+}