metadata-connect 1.1.2 → 1.1.3

package/dist/extract.d.ts

@@ -1,4 +1,5 @@
 import type { ExtractedMetadata, FileReader, MetadataParser } from './types.js';
+import type { Logger } from './types/logger.js';
 /**
  * Get the appropriate parser for a file extension
  */
@@ -11,10 +12,18 @@ export declare function getSupportedExtensions(): string[];
  * Check if a file extension is supported
  */
 export declare function isExtensionSupported(extension: string): boolean;
+/**
+ * Options for extractMetadata
+ */
+export interface ExtractMetadataOptions {
+    /** Optional logger instance. If omitted, logging is silently disabled. */
+    logger?: Logger;
+}
 /**
  * Extract metadata from an audio file using the appropriate parser
  *
  * @param reader - FileReader interface for reading file data
+ * @param options - Optional configuration including logger
  * @returns Extracted metadata, or null if extraction fails or format is unsupported
  *
  * @example
@@ -32,5 +41,5 @@ export declare function isExtensionSupported(extension: string): boolean;
  * }
  * ```
  */
-export declare function extractMetadata(reader: FileReader): Promise<ExtractedMetadata | null>;
+export declare function extractMetadata(reader: FileReader, options?: ExtractMetadataOptions): Promise<ExtractedMetadata | null>;
 //# sourceMappingURL=extract.d.ts.map

package/dist/extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA6BhF;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAG9E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAa3F"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AA8BhD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAG9E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAsBnC"}

package/dist/extract.js

@@ -1,3 +1,4 @@
+import { noopLogger } from './types/logger.js';
 import { extractFromMp3 } from './parsers/id3.js';
 import { extractFromMp4 } from './parsers/mp4.js';
 import { extractFromFlac } from './parsers/flac.js';
@@ -44,6 +45,7 @@ export function isExtensionSupported(extension) {
  * Extract metadata from an audio file using the appropriate parser
  *
  * @param reader - FileReader interface for reading file data
+ * @param options - Optional configuration including logger
  * @returns Extracted metadata, or null if extraction fails or format is unsupported
  *
  * @example
@@ -61,16 +63,26 @@ export function isExtensionSupported(extension) {
  * }
  * ```
  */
-export async function extractMetadata(reader) {
+export async function extractMetadata(reader, options) {
+    const logger = options?.logger ?? noopLogger;
     const parser = getParserForExtension(reader.extension);
     if (!parser) {
+        logger.debug('No parser found for extension: %s', reader.extension);
         return null;
     }
     try {
-        return await parser(reader);
+        logger.debug('Extracting metadata from %s file (%d bytes)', reader.extension, reader.size);
+        const result = await parser(reader);
+        if (result) {
+            logger.debug('Extracted metadata: title=%s, artist=%s', result.title ?? '(none)', result.artist ?? '(none)');
+        }
+        else {
+            logger.debug('Parser returned null for %s file', reader.extension);
+        }
+        return result;
     }
-    catch {
-        // Return null on any parsing error
+    catch (err) {
+        logger.warn('Failed to extract metadata from %s file: %s', reader.extension, err);
         return null;
     }
 }

package/dist/extract.js.map

@@ -1 +1 @@
-{"version":3,"file":"extract.js","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;GAEG;AACH,MAAM,UAAU,GAAmC;IACjD,MAAM;IACN,GAAG,EAAE,cAAc;IAEnB,cAAc;IACd,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IAEnB,OAAO;IACP,IAAI,EAAE,eAAe;IAErB,OAAO;IACP,IAAI,EAAE,eAAe;IACrB,GAAG,EAAE,eAAe;IACpB,IAAI,EAAE,eAAe;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAiB;IACrD,MAAM,aAAa,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACjE,OAAO,UAAU,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,OAAO,qBAAqB,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAkB;IACtD,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAEvD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,mCAAmC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;GAEG;AACH,MAAM,UAAU,GAAmC;IACjD,MAAM;IACN,GAAG,EAAE,cAAc;IAEnB,cAAc;IACd,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IAEnB,OAAO;IACP,IAAI,EAAE,eAAe;IAErB,OAAO;IACP,IAAI,EAAE,eAAe;IACrB,GAAG,EAAE,eAAe;IACpB,IAAI,EAAE,eAAe;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAiB;IACrD,MAAM,aAAa,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACjE,OAAO,UAAU,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,OAAO,qBAAqB,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;AACnD,CAAC;AAUD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAkB,EAClB,OAAgC;IAEhC,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,UAAU,CAAC;IAC7C,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAEvD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,CAAC,KAAK,CAAC,mCAAmC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,CAAC,6CAA6C,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,KAAK,CAAC,yCAAyC,EAAE,MAAM,CAAC,KAAK,IAAI,QAAQ,EAAE,MAAM,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC;QAC/G,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,KAAK,CAAC,kCAAkC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,6CAA6C,EAAE,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAClF,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export { extractMetadata, getParserForExtension, getSupportedExtensions, isExtensionSupported, } from './extract.js';
+export type { ExtractMetadataOptions } from './extract.js';
 export type { FileReader, ExtractedMetadata, ArtworkMimeType, MetadataParser, } from './types.js';
 export { PictureType } from './types.js';
+export type { Logger } from './types/logger.js';
+export { noopLogger } from './types/logger.js';
 export { createBufferReader } from './reader.js';
 export { extractFromMp3, extractFromMp4, extractFromFlac, extractFromAiff, detectImageType, normalizeMimeType, } from './parsers/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EACL,cAAc,EACd,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAG3D,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,YAAY,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EACL,cAAc,EACd,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 // Main extraction function
 export { extractMetadata, getParserForExtension, getSupportedExtensions, isExtensionSupported, } from './extract.js';
 export { PictureType } from './types.js';
+export { noopLogger } from './types/logger.js';
 // Reader utilities
 export { createBufferReader } from './reader.js';
 // Individual parsers (for advanced use cases)

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAStB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,8CAA8C;AAC9C,OAAO,EACL,cAAc,EACd,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAUtB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAIzC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,8CAA8C;AAC9C,OAAO,EACL,cAAc,EACd,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}

package/dist/types/logger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Logger interface for metadata-connect.
+ * Allows consumers to inject their own logger implementation.
+ */
+export interface Logger {
+    trace(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+export declare const noopLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/types/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/types/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC7C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC9C;AAED,eAAO,MAAM,UAAU,EAAE,MAMxB,CAAC"}

package/dist/types/logger.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Logger interface for metadata-connect.
+ * Allows consumers to inject their own logger implementation.
+ */
+export const noopLogger = {
+    trace() { },
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+//# sourceMappingURL=logger.js.map

package/dist/types/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/types/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,MAAM,CAAC,MAAM,UAAU,GAAW;IAChC,KAAK,KAAI,CAAC;IACV,KAAK,KAAI,CAAC;IACV,IAAI,KAAI,CAAC;IACT,IAAI,KAAI,CAAC;IACT,KAAK,KAAI,CAAC;CACX,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metadata-connect",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Extract audio metadata (title, artist, album, BPM, key, artwork) from MP3, M4A, FLAC, and AIFF files with minimal network transfer using partial file reads",
   "main": "dist/index.js",
   "module": "dist/index.js",