tiny-essentials 1.28.1 → 1.28.2

package/dist/v1/basics/mediaContent.d.mts

@@ -1,43 +1,10 @@
-/** @type {Map<string, number>} */
-export const _blobCounter: Map<string, number>;
-export function getMediaContentBase(): MediaContentBase;
-export function getMediaContentMetadata(): MediaContentMetadata;
 /**
- * Custom error class to provide detailed context during the content preparation process.
- * @extends Error
+ * A type representing either a static string or a function that returns a string, used to resolve an unknown artist's name.
+ * @typedef {string|(() => string)} UnknownArtistGetter
  */
-export class MediaLoadingError extends Error {
-    /**
-     * @param {string} message - Human-readable error message.
-     * @param {string} url - The URL that caused the error.
-     * @param {LoadingErrorStage} stage - The stage where the error occurred.
-     */
-    constructor(message: string, url: string, stage: LoadingErrorStage);
-    url: string;
-    stage: LoadingErrorStage;
-}
-export function generateSimpleHash(str: string): Promise<string>;
-export function convertToBlobUrl(data: Uint8Array | string, format?: string): string;
-export function blobUrlToBase64(url: string): Promise<string>;
-export function revokeContentUrls(content: MediaContent): void;
-export function valMediaContentMetadata(common: ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>): void;
-export function valMediaContentMetadataPartial(common: Partial<ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>>): void;
-export function extractMediaId3Tags(url: string, parseFile: ParseMediaContentMetadata): Promise<MediaContentMetadata>;
-export function parseMediaMetadata(source: string | HTMLMediaElement, defaultMetadata?: Partial<MediaContentBase & MediaContentMetadata> & {
-    id?: string;
-    weight?: number;
-}, metadata?: Partial<MediaContentBase & MediaContentMetadata> & {
-    id?: string;
-    weight?: number;
-}, parseFile?: ParseMediaContentMetadata, callbacks?: {
-    onProgress?: ((progress: LoadingMediaProgress) => void) | undefined;
-    onError?: ((error: MediaLoadingErrorData) => void) | undefined;
-}, unknownArtist?: UnknownArtistGetter): Promise<MediaContent>;
 export type UnknownArtistGetter = string | (() => string);
-/**
- * Represents an image attachment template.
- */
-export type IPictureTemplate<PictureData extends Uint8Array | string> = {
+export type PictureDataType = Uint8Array | string;
+export type IPictureTemplate<PictureData extends PictureDataType> = {
     /**
      * - The MIME type of the image (e.g., 'image/jpeg').
      */
@@ -49,31 +16,22 @@ export type IPictureTemplate<PictureData extends Uint8Array | string> = {
     /**
      * - An optional textual description of the image.
      */
-    description?: string | undefined;
+    description?: string;
     /**
      * - The specific type of picture (e.g., 'cover', 'front', 'back').
      */
-    type?: string | undefined;
+    type?: string;
     /**
      * - The filename associated with the image.
      */
-    name?: string | undefined;
+    name?: string;
 };
-/**
- * Represents an image attachment, such as album art.
- */
 export type IPicture = IPictureTemplate<string>;
-/**
- * A numeric structure representing track or disk indexing.
- */
 export type MediaNumber = {
     no: number | null;
     of: number | null;
 };
-/**
- * This metadata structure is modeled template.
- */
-export type ContentMetadataTemplate<IPictureContent extends IPictureTemplate<Uint8Array | string>> = {
+export type ContentMetadataTemplate<IPictureContent extends IPictureTemplate<PictureDataType>> = {
     /**
      * - The title of the track.
      */
@@ -125,16 +83,9 @@ export type ContentMetadataTemplate<IPictureContent extends IPictureTemplate<Uin
     /**
      * - An array of picture objects containing album art.
      */
-    picture?: IPictureContent[] | undefined;
+    picture?: IPictureContent[];
 };
-/**
- * This metadata structure is modeled after the standard output of the
- * `music-metadata@11.13.0` npm package.
- */
-export type MediaContentMetadata = ContentMetadataTemplate<IPicture>;
-/**
- * The core properties required for any content item within the media system.
- */
+export type MediaContentMetadata<PictureData extends PictureDataType> = ContentMetadataTemplate<IPictureTemplate<PictureData>>;
 export type MediaContentBase = {
     /**
      * - Unique identifier.
@@ -159,24 +110,17 @@ export type MediaContentBase = {
     /**
      * - Probability multiplier for random selection mode.
      */
-    weight?: number | undefined;
+    weight?: number;
 };
-/**
- * The final content object used within the media, combining
- * core playback properties with rich metadata.
- */
-export type MediaContent = MediaContentBase & MediaContentMetadata;
-/**
- * A promise that resolves to an object containing the extracted metadata.
- */
+export type MediaContent<PictureData extends PictureDataType> = MediaContentBase & MediaContentMetadata<PictureData>;
 export type ParseMediaContentMetadata = (data: Blob) => Promise<{
-    common: Partial<ContentMetadataTemplate<IPictureTemplate<Uint8Array | string>>>;
+    common: Partial<ContentMetadataTemplate<IPictureTemplate<PictureDataType>>>;
 }>;
 export type LoadingMediaProgress = {
     /**
      * - The current status of the operation.
      */
-    status: "loading" | "success";
+    status: 'loading' | 'success';
     /**
      * - The current execution stage.
      */
@@ -184,14 +128,14 @@ export type LoadingMediaProgress = {
     /**
      * - The current loading event.
      */
-    event?: ProgressEvent<EventTarget> | undefined;
+    event?: ProgressEvent<EventTarget>;
     /**
      * - The URL being processed.
      */
     url: string;
 };
-export type LoadingProgressStage = "INITIALIZING" | "DOWNLOADING" | "METADATA_LOADED" | "EXTRACTING_ID3" | "COMPLETE";
-export type LoadingErrorStage = "INITIALIZING" | "DOWNLOADING" | "METADATA" | "ID3" | "UNKNOWN";
+export type LoadingProgressStage = 'INITIALIZING' | 'DOWNLOADING' | 'METADATA_LOADED' | 'EXTRACTING_ID3' | 'COMPLETE';
+export type LoadingErrorStage = 'INITIALIZING' | 'DOWNLOADING' | 'METADATA' | 'ID3' | 'UNKNOWN';
 export type MediaLoadingErrorData = {
     /**
      * - The original error object.
@@ -206,4 +150,131 @@ export type MediaLoadingErrorData = {
      */
     stage: LoadingErrorStage;
 };
+/** @type {Map<string, number>} */
+export declare const _blobCounter: Map<string, number>;
+/**
+ * Returns a new object initialized with the default values for the core media content properties.
+ * @returns {MediaContentBase}
+ */
+export declare const getMediaContentBase: () => MediaContentBase;
+/**
+ * Returns a new object initialized with the default values for the media content metadata properties.
+ * @returns {MediaContentMetadata<PictureDataType>}
+ */
+export declare const getMediaContentMetadata: () => MediaContentMetadata<PictureDataType>;
+/**
+ * Custom error class to provide detailed context during the content preparation process.
+ * @extends Error
+ */
+export declare class MediaLoadingError extends Error {
+    url: string;
+    stage: LoadingErrorStage;
+    /**
+     * @param {string} message - Human-readable error message.
+     * @param {string} url - The URL that caused the error.
+     * @param {LoadingErrorStage} stage - The stage where the error occurred.
+     */
+    constructor(message: string, url: string, stage: LoadingErrorStage);
+}
+/**
+ * Internal helper to generate a deterministic ID from a string.
+ * @param {string} str
+ * @returns {Promise<string>}
+ * @private
+ */
+export declare const generateSimpleHash: (str: string) => Promise<string>;
+/**
+ * Helper to convert Uint8Array or Base64 string directly into a high performance Blob URL.
+ * @param {PictureDataType} data
+ * @param {string} format
+ * @returns {string} The generated Blob URL or original string if already valid.
+ */
+export declare const convertToBlobUrl: (data: PictureDataType, format?: string) => string;
+/**
+ * Asynchronous helper to convert a Blob URL back to Base64 (Date URL) at export time.
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
+export declare const blobUrlToBase64: (url: string) => Promise<string>;
+/**
+ * Safely revokes Blob URLs to prevent memory leaks from createObjectURL.
+ * @template {PictureDataType} PictureData
+ * @param {MediaContent<PictureData>} content
+ */
+export declare const revokeContentUrls: <PictureData extends PictureDataType>(content: MediaContent<PictureData>) => void;
+/**
+ * Helper to validate types within the media content metadata object.
+ * This ensures that if a property is present, it matches the expected type.
+ * @param {ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>} common
+ */
+export declare const valMediaContentMetadata: (common: ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>) => void;
+/**
+ * Helper to validate types within the media content metadata object.
+ * Allows the absence of properties (useful for updates/patch).
+ * @param {Partial<ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>>} common
+ */
+export declare const valMediaContentMetadataPartial: (common: Partial<ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>>) => void;
+/**
+ * Downloads an audio file from a URL and extracts its ID3/metadata tags.
+ *
+ * @param {string} url - The full URL of the audio file to be downloaded.
+ * @param {ParseMediaContentMetadata} parseFile - The function used to parse the file data.
+ * @returns {Promise<MediaContentMetadata<string>>} A promise that resolves to an object containing the extracted metadata.
+ * @throws {TypeError} If the provided `url` is not a string or `parseFile` is not a function.
+ * @throws {Error} If the network request fails or the parsing process encounters an error.
+ */
+export declare const extractMediaId3Tags: (url: string, parseFile: ParseMediaContentMetadata) => Promise<MediaContentMetadata<string>>;
+/**
+ * A Static Factory Method that prepares a MediaContent object by
+ * extracting metadata from an audio source.
+ *
+ * @template {PictureDataType} PictureData
+ * @param {string | HTMLMediaElement} source - A URL string or an existing Audio object.
+ * @param {Partial<MediaContentBase & MediaContentMetadata<PictureData>> & { id?: string; weight?: number }} [defaultMetadata={}] - Optional default metadata that overrides automatic extraction.
+ * @param {Partial<MediaContentBase & MediaContentMetadata<PictureData>> & { id?: string; weight?: number }} [metadata={}] - Optional manual metadata that overrides automatic extraction.
+ * @param {ParseMediaContentMetadata} [parseFile] - Private helper to interface with parseFile.
+ * @param {Object} [callbacks={}] - Callbacks for monitoring the loading process.
+ * @param {(progress: LoadingMediaProgress) => void} [callbacks.onProgress] - Callback triggered on stage changes.
+ * @param {(error: MediaLoadingErrorData) => void} [callbacks.onError] - Callback triggered when a non-fatal or fatal error occurs.
+ * @param {UnknownArtistGetter} unknownArtist
+ * @returns {Promise<MediaContent<PictureData>>} A promise that resolves to a valid MediaContent object.
+ * @throws {MediaLoadingError} If the preparation process fails at any stage.
+ *
+ * @example
+ * // Usage with URL
+ * import { parseBlob } from 'music-metadata';
+ * const track = await parseMediaMetadata('/assets/song.mp3', {}, { title: 'My Song', artist: 'Artist' }, parseBlob);
+ * media.add('music', track);
+ *
+ * @example
+ * // Usage with Audio Object
+ * import { parseBlob } from 'music-metadata';
+ * const audio = new Audio();
+ * audio.src = '/assets/song.mp3';
+ * const track = await parseMediaMetadata(audio, {}, {}, parseBlob);
+ * media.add('music', track);
+ *
+ * @example
+ * // Usage with tracking
+ * const track = await parseMediaMetadata(
+ *   '/assets/song.mp3',
+ *   {},
+ *   {},
+ *   parseBlob,
+ *   {
+ *     onProgress: (p) => console.log(`[${p.stage}] ${p.status}`),
+ *     onError: (e) => console.error(`Failed at ${e.stage} for ${e.url}: ${e.error.message}`)
+ *   }
+ * );
+ */
+export declare const parseMediaMetadata: <PictureData extends PictureDataType>(source: string | HTMLMediaElement, defaultMetadata?: Partial<MediaContentBase & MediaContentMetadata<PictureData>> & {
+    id?: string;
+    weight?: number;
+}, metadata?: Partial<MediaContentBase & MediaContentMetadata<PictureData>> & {
+    id?: string;
+    weight?: number;
+}, parseFile?: ParseMediaContentMetadata, callbacks?: {
+    onProgress?: (progress: LoadingMediaProgress) => void;
+    onError?: (error: MediaLoadingErrorData) => void;
+}, unknownArtist?: UnknownArtistGetter) => Promise<MediaContent<PictureData>>;
 //# sourceMappingURL=mediaContent.d.mts.map

package/dist/v1/basics/mediaContent.mjs

@@ -1,9 +1,14 @@
 /**
+ * A type representing either a static string or a function that returns a string, used to resolve an unknown artist's name.
  * @typedef {string|(() => string)} UnknownArtistGetter
  */
+/**
+ * Represents the data type for images, which can be raw binary (Uint8Array) or a string (such as a Blob URL or Data URL).
+ * @typedef {Uint8Array|string} PictureDataType
+ */
 /**
  * Represents an image attachment template.
- * @template {Uint8Array|string} PictureData
+ * @template {PictureDataType} PictureData
  * @typedef {Object} IPictureTemplate
  * @property {string} format - The MIME type of the image (e.g., 'image/jpeg').
  * @property {PictureData} data - The raw binary data of the image.
@@ -22,7 +27,7 @@
 /**
  * This metadata structure is modeled template.
  *
- * @template {IPictureTemplate<Uint8Array|string>} IPictureContent
+ * @template {IPictureTemplate<PictureDataType>} IPictureContent
  * @typedef {Object} ContentMetadataTemplate
  * @property {string|null} title - The title of the track.
  * @property {string|null} album - The name of the album.
@@ -42,7 +47,8 @@
  * This metadata structure is modeled after the standard output of the
  * `music-metadata@11.13.0` npm package.
  *
- * @typedef {ContentMetadataTemplate<IPicture>} MediaContentMetadata
+ * @template {PictureDataType} PictureData
+ * @typedef {ContentMetadataTemplate<IPictureTemplate<PictureData>>} MediaContentMetadata
  */
 /**
  * The core properties required for any content item within the media system.
@@ -58,29 +64,33 @@
  * The final content object used within the media, combining
  * core playback properties with rich metadata.
  *
- * @typedef {MediaContentBase & MediaContentMetadata} MediaContent
+ * @template {PictureDataType} PictureData
+ * @typedef {MediaContentBase & MediaContentMetadata<PictureData>} MediaContent
  */
 //////////////////////////////////////////////////////////////////
 /**
  * A promise that resolves to an object containing the extracted metadata.
  * @callback ParseMediaContentMetadata
  * @param {Blob} data - The raw file blob.
- * @returns {Promise<{ common: Partial<ContentMetadataTemplate<IPictureTemplate<Uint8Array|string>>> }>} A promise resolving to the common metadata properties.
+ * @returns {Promise<{ common: Partial<ContentMetadataTemplate<IPictureTemplate<PictureDataType>>> }>} A promise resolving to the common metadata properties.
  */
 /**
- * @typedef {Object} LoadingMediaProgress
+ * @typedef {Object} LoadingMediaProgress Represents the current state of a media loading operation, including its status, execution stage, and the URL being processed.
  * @property {'loading'|'success'} status - The current status of the operation.
  * @property {LoadingProgressStage} stage - The current execution stage.
  * @property {ProgressEvent<EventTarget>} [event] - The current loading event.
  * @property {string} url - The URL being processed.
  */
 /**
+ * Defines the specific execution stages of a successful loading process.
  * @typedef {'INITIALIZING'|'DOWNLOADING'|'METADATA_LOADED'|'EXTRACTING_ID3'|'COMPLETE'} LoadingProgressStage
  */
 /**
+ * Defines the specific stages where a loading error might occur.
  * @typedef {'INITIALIZING'|'DOWNLOADING'|'METADATA'|'ID3'|'UNKNOWN'} LoadingErrorStage
  */
 /**
+ * A data structure containing details about a media loading error.
  * @typedef {Object} MediaLoadingErrorData
  * @property {Error} error - The original error object.
  * @property {string} url - The URL that failed.
@@ -88,21 +98,30 @@
  */
 //////////////////////////////////////////////////////////////////
 const checkString = (/** @type {string} */ val, /** @type {string} */ name) => {
+    if (typeof name !== 'string')
+        throw new TypeError('Expected "name" to be a string.');
     if (typeof val !== 'string')
         throw new TypeError(`Expected "${name}" to be a string, but received ${typeof val}.`);
 };
 const checkFunction = (/** @type {Function} */ val, /** @type {string} */ name) => {
+    if (typeof name !== 'string')
+        throw new TypeError('Expected "name" to be a string.');
     if (typeof val !== 'function')
         throw new TypeError(`Expected "${name}" to be a function, but received ${typeof val}.`);
 };
 const checkObject = (/** @type {Object<string, any> | null} */ val, /** @type {string} */ name) => {
+    if (typeof name !== 'string')
+        throw new TypeError('Expected "name" to be a string.');
     if (typeof val !== 'object' || val === null || Array.isArray(val)) {
         throw new TypeError(`Expected "${name}" to be a plain object, but received ${val === null ? 'null' : Array.isArray(val) ? 'array' : typeof val}.`);
     }
 };
 /** @type {Map<string, number>} */
 export const _blobCounter = new Map();
-/** @returns {MediaContentBase} */
+/**
+ * Returns a new object initialized with the default values for the core media content properties.
+ * @returns {MediaContentBase}
+ */
 export const getMediaContentBase = () => ({
     id: '',
     title: '',
@@ -111,7 +130,10 @@ export const getMediaContentBase = () => ({
     duration: 0,
     weight: 1,
 });
-/** @returns {MediaContentMetadata} */
+/**
+ * Returns a new object initialized with the default values for the media content metadata properties.
+ * @returns {MediaContentMetadata<PictureDataType>}
+ */
 export const getMediaContentMetadata = () => ({
     title: null,
     album: null,
@@ -167,7 +189,7 @@ export const generateSimpleHash = async (str) => {
 };
 /**
  * Helper to convert Uint8Array or Base64 string directly into a high performance Blob URL.
- * @param {Uint8Array|string} data
+ * @param {PictureDataType} data
  * @param {string} format
  * @returns {string} The generated Blob URL or original string if already valid.
  */
@@ -225,7 +247,8 @@ export const blobUrlToBase64 = async (url) => {
 };
 /**
  * Safely revokes Blob URLs to prevent memory leaks from createObjectURL.
- * @param {MediaContent} content
+ * @template {PictureDataType} PictureData
+ * @param {MediaContent<PictureData>} content
  */
 export const revokeContentUrls = (content) => {
     checkObject(content, 'content');
@@ -258,6 +281,7 @@ const validateMediaContent = (common, isPartial) => {
     const isArray = (
     /** @type {string[] | IPictureTemplate<string|Uint8Array>[] | undefined} */ v, 
     /** @type {(value: any, index: number, array: any[]) => any} */ valueValidator) => {
+        checkFunction(valueValidator, 'valueValidator');
         if (isUndefinedAllowed(v))
             return true;
         if (Array.isArray(v) && v.every(valueValidator))
@@ -296,10 +320,11 @@ const validateMediaContent = (common, isPartial) => {
         throw new TypeError('Invalid metadata: "picture" must be an array of pictures.');
     /**
      * Validate Nested Objects (Disk and Track)
+     * @param {string} name
      * @param {MediaNumber|null} [info]
-     * @param {string} [name]
      */
-    const validateTrackInfo = (info, name) => {
+    const validateTrackInfo = (name, info) => {
+        checkString(name, 'name');
         if (isUndefinedAllowed(info))
             return; // Ignores if partial
         if (info === undefined || info === null) {
@@ -312,27 +337,33 @@ const validateMediaContent = (common, isPartial) => {
         if (typeof info.of !== 'number' && info.of !== null)
             throw new TypeError(`Invalid metadata: "${name}.of" must be a number or null.`);
     };
-    validateTrackInfo(common.disk, 'disk');
-    validateTrackInfo(common.track, 'track');
+    validateTrackInfo('disk', common.disk);
+    validateTrackInfo('track', common.track);
 };
 /**
  * Helper to validate types within the media content metadata object.
  * This ensures that if a property is present, it matches the expected type.
  * @param {ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>} common
  */
-export const valMediaContentMetadata = (common) => validateMediaContent(common, false);
+export const valMediaContentMetadata = (common) => {
+    checkObject(common, 'common');
+    return validateMediaContent(common, false);
+};
 /**
  * Helper to validate types within the media content metadata object.
  * Allows the absence of properties (useful for updates/patch).
  * @param {Partial<ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>>} common
  */
-export const valMediaContentMetadataPartial = (common) => validateMediaContent(common, true);
+export const valMediaContentMetadataPartial = (common) => {
+    checkObject(common, 'common');
+    return validateMediaContent(common, true);
+};
 /**
  * Downloads an audio file from a URL and extracts its ID3/metadata tags.
  *
  * @param {string} url - The full URL of the audio file to be downloaded.
  * @param {ParseMediaContentMetadata} parseFile - The function used to parse the file data.
- * @returns {Promise<MediaContentMetadata>} A promise that resolves to an object containing the extracted metadata.
+ * @returns {Promise<MediaContentMetadata<string>>} A promise that resolves to an object containing the extracted metadata.
  * @throws {TypeError} If the provided `url` is not a string or `parseFile` is not a function.
  * @throws {Error} If the network request fails or the parsing process encounters an error.
  */
@@ -384,15 +415,16 @@ export const extractMediaId3Tags = async (url, parseFile) => {
  * A Static Factory Method that prepares a MediaContent object by
  * extracting metadata from an audio source.
  *
+ * @template {PictureDataType} PictureData
  * @param {string | HTMLMediaElement} source - A URL string or an existing Audio object.
- * @param {Partial<MediaContentBase & MediaContentMetadata> & { id?: string; weight?: number }} [defaultMetadata={}] - Optional default metadata that overrides automatic extraction.
- * @param {Partial<MediaContentBase & MediaContentMetadata> & { id?: string; weight?: number }} [metadata={}] - Optional manual metadata that overrides automatic extraction.
+ * @param {Partial<MediaContentBase & MediaContentMetadata<PictureData>> & { id?: string; weight?: number }} [defaultMetadata={}] - Optional default metadata that overrides automatic extraction.
+ * @param {Partial<MediaContentBase & MediaContentMetadata<PictureData>> & { id?: string; weight?: number }} [metadata={}] - Optional manual metadata that overrides automatic extraction.
  * @param {ParseMediaContentMetadata} [parseFile] - Private helper to interface with parseFile.
  * @param {Object} [callbacks={}] - Callbacks for monitoring the loading process.
  * @param {(progress: LoadingMediaProgress) => void} [callbacks.onProgress] - Callback triggered on stage changes.
  * @param {(error: MediaLoadingErrorData) => void} [callbacks.onError] - Callback triggered when a non-fatal or fatal error occurs.
  * @param {UnknownArtistGetter} unknownArtist
- * @returns {Promise<MediaContent>} A promise that resolves to a valid MediaContent object.
+ * @returns {Promise<MediaContent<PictureData>>} A promise that resolves to a valid MediaContent object.
  * @throws {MediaLoadingError} If the preparation process fails at any stage.
  *
  * @example
@@ -422,7 +454,9 @@ export const extractMediaId3Tags = async (url, parseFile) => {
  *   }
  * );
  */
-export const parseMediaMetadata = async (source, defaultMetadata = {}, metadata = {}, parseFile = (url) => {
+export const parseMediaMetadata = async (source, defaultMetadata = {}, metadata = {}, parseFile = (data) => {
+    if (!(data instanceof Blob))
+        throw new TypeError('Expected "data" to be a Blob.');
     return new Promise((resolve, reject) => reject(new TypeError('parseFile library not found.')));
 }, callbacks = {}, unknownArtist = 'null') => {
     // Argument Validation
@@ -448,6 +482,10 @@ export const parseMediaMetadata = async (source, defaultMetadata = {}, metadata
      * @param {ProgressEvent<EventTarget>} [event]
      */
     const notifyProgress = (stage, event) => {
+        checkString(stage, 'stage');
+        if (event !== undefined && !(event instanceof Event)) {
+            throw new TypeError('Expected "event" to be an Event or undefined.');
+        }
         if (callbacks.onProgress) {
             callbacks.onProgress({
                 event,
@@ -458,6 +496,9 @@ export const parseMediaMetadata = async (source, defaultMetadata = {}, metadata
         }
     };
     const notifyError = (/** @type {Error} */ error, /** @type {LoadingErrorStage} */ stage) => {
+        if (!(error instanceof Error))
+            throw new TypeError('Expected "error" to be an Error.');
+        checkString(stage, 'stage'); // Adicionado
         if (callbacks.onError) {
             callbacks.onError({
                 error,
@@ -522,7 +563,7 @@ export const parseMediaMetadata = async (source, defaultMetadata = {}, metadata
             weight: metadata.weight ?? 1,
         };
         // 4. Automatic Metadata Extraction (ID3 Tags)
-        /** @type {Partial<MediaContentMetadata>} */
+        /** @type {Partial<MediaContentMetadata<string>>} */
         let extractedMetadata = {};
         notifyProgress('EXTRACTING_ID3');
         try {
@@ -540,6 +581,7 @@ export const parseMediaMetadata = async (source, defaultMetadata = {}, metadata
          * @returns {string}
          */
         const getFallbackTitleFromUrl = (url) => {
+            checkString(url, 'url');
             try {
                 // Remove query params or hashes, get the last segment, and strip extension
                 const filename = url.split(/[?#]/)[0].split('/').pop();
@@ -570,7 +612,7 @@ export const parseMediaMetadata = async (source, defaultMetadata = {}, metadata
                 url: url,
             });
         }
-        return /** @type {MediaContent} */ (finalContent);
+        return /** @type {MediaContent<PictureData>} */ (finalContent);
     }
     catch (err) {
         // If it's already a MediaLoadingError, re-throw it.

package/dist/v1/basics/objChecker.d.mts

@@ -10,7 +10,7 @@
  * countObj({ a: 1, b: 2 }); // 2
  * countObj('not an object'); // Throws TypeError
  */
-export function countObj(obj: Array<any> | Record<string | number | symbol, any>): number;
+export declare function countObj(obj: Array<any> | Record<string | number | symbol, any>): number;
 /**
  * Determines whether a given value is a pure JSON object (plain object).
  *
@@ -26,5 +26,5 @@ export function countObj(obj: Array<any> | Record<string | number | symbol, any>
  * @param {unknown} value - The value to test.
  * @returns {value is Record<string | number | symbol, unknown>} Returns true if the value is a pure object.
  */
-export function isJsonObject(value: unknown): value is Record<string | number | symbol, unknown>;
+export declare function isJsonObject(value: unknown): value is Record<string | number | symbol, unknown>;
 //# sourceMappingURL=objChecker.d.mts.map

package/dist/v1/basics/objFilter.cjs

@@ -272,7 +272,10 @@ extendObjType([
   ],
   [
     'array',
-    /** @param {*} val @returns {val is any[]} */
+    /**
+     * @template {any} Value
+     * @param {*} val @returns {val is Value[]}
+     */
     (val) => Array.isArray(val),
   ],
 ]);
@@ -300,27 +303,44 @@ extendObjType([
   ],
   [
     'map',
-    /** @param {*} val @returns {val is Map<unknown, unknown>} */
+    /**
+     * @template {any} Key
+     * @template {any} Value
+     * @param {*} val @returns {val is Map<Key, Value>}
+     */
     (val) => val instanceof Map,
   ],
   [
     'set',
-    /** @param {*} val @returns {val is Set<unknown>} */
+    /**
+     * @template {any} Value
+     * @param {*} val @returns {val is Set<Value>}
+     */
     (val) => val instanceof Set,
   ],
   [
     'weakmap',
-    /** @param {*} val @returns {val is WeakMap<unknown, unknown>} */
+    /**
+     * @template {WeakKey} Key
+     * @template {any} Value
+     * @param {*} val @returns {val is WeakMap<Key, Value>}
+     */
     (val) => val instanceof WeakMap,
   ],
   [
     'weakset',
-    /** @param {*} val @returns {val is WeakSet<unknown>} */
+    /**
+     * @template {WeakKey} Value
+     * @param {*} val @returns {val is WeakSet<Value>}
+     */
     (val) => val instanceof WeakSet,
   ],
   [
     'promise',
-    /** @param {*} val @returns {val is Promise<unknown>} */
+    /**
+     * @template {any} Value
+     * @param {*} val @returns {val is Promise<Value>}
+     */
     (val) => val instanceof Promise,
   ],
 ]);
@@ -338,7 +358,11 @@ if (isBrowser) {
 extendObjType([
   [
     'object',
-    /** @param {*} val @returns {val is Record<string | number | symbol, unknown>} */
+    /**
+     * @template {string | number | symbol} Key
+     * @template {any} Value
+     * @param {*} val @returns {val is Record<Key, Value>}
+     */
     (val) => objChecker.isJsonObject(val),
   ],
 ]);