tiny-essentials 1.28.0 → 1.28.2

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

@@ -1,66 +1,12 @@
-import { valMediaContentMetadata } from './mediaContent.mjs';
-import { valMediaContentMetadataPartial } from './mediaContent.mjs';
-import { parseMediaMetadata } from './mediaContent.mjs';
-import { extractMediaId3Tags } from './mediaContent.mjs';
-import { diffStrings } from './text.mjs';
-import { diffArrayList } from './array.mjs';
-import { breakdownDuration } from './clock.mjs';
-import { calculateMarketcap } from './simpleMath.mjs';
-import { compareMarketcap } from './simpleMath.mjs';
-import { getPercentage } from './simpleMath.mjs';
-import { areElsCollTop } from './collision.mjs';
-import { areElsCollBottom } from './collision.mjs';
-import { areElsCollLeft } from './collision.mjs';
-import { areElsCollRight } from './collision.mjs';
-import { areElsCollPerfTop } from './collision.mjs';
-import { areElsCollPerfBottom } from './collision.mjs';
-import { areElsCollPerfLeft } from './collision.mjs';
-import { areElsCollPerfRight } from './collision.mjs';
-import { areElsColliding } from './collision.mjs';
-import { areElsPerfColliding } from './collision.mjs';
-import { getElsColliding } from './collision.mjs';
-import { getElsPerfColliding } from './collision.mjs';
-import { getElsCollOverlap } from './collision.mjs';
-import { getElsCollOverlapPos } from './collision.mjs';
-import { getRectCenter } from './collision.mjs';
-import { getElsRelativeCenterOffset } from './collision.mjs';
-import { getElsCollDirDepth } from './collision.mjs';
-import { getElsCollDetails } from './collision.mjs';
-import { safeTextTrim } from './text.mjs';
-import { installWindowHiddenScript } from './html.mjs';
-import { genFibonacciSeq } from './simpleMath.mjs';
-import { fetchJson } from './html.mjs';
-import { fetchText } from './html.mjs';
-import { readJsonBlob } from './html.mjs';
-import { readFileBlob } from './html.mjs';
-import { readBase64Blob } from './html.mjs';
-import { saveJsonFile } from './html.mjs';
-import { documentIsFullScreen } from './fullScreen.mjs';
-import { isScreenFilled } from './fullScreen.mjs';
-import { requestFullScreen } from './fullScreen.mjs';
-import { exitFullScreen } from './fullScreen.mjs';
-import { isFullScreenMode } from './fullScreen.mjs';
-import { onFullScreenChange } from './fullScreen.mjs';
-import { offFullScreenChange } from './fullScreen.mjs';
-import { isJsonObject } from './objChecker.mjs';
-import { arraySortPositions } from './array.mjs';
-import { formatBytes } from './simpleMath.mjs';
-import { addAiMarkerShortcut } from './text.mjs';
-import { extendObjType } from './objFilter.mjs';
-import { reorderObjTypeOrder } from './objFilter.mjs';
-import { cloneObjTypeOrder } from './objFilter.mjs';
-import { countObj } from './objChecker.mjs';
-import { objType } from './objFilter.mjs';
-import { ruleOfThree } from './simpleMath.mjs';
-import { getSimplePerc } from './simpleMath.mjs';
-import { asyncReplace } from './text.mjs';
-import { getAge } from './simpleMath.mjs';
-import { formatCustomTimer } from './clock.mjs';
-import { formatDayTimer } from './clock.mjs';
-import { formatTimer } from './clock.mjs';
-import { getTimeDuration } from './clock.mjs';
-import { shuffleArray } from './array.mjs';
-import { toTitleCase } from './text.mjs';
-import { toTitleCaseLowerFirst } from './text.mjs';
-export { valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
+import { diffArrayList, shuffleArray, arraySortPositions, multiplyArrayBlocks } from './array.mjs';
+import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration } from './clock.mjs';
+import { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, fetchText } from './html.mjs';
+import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType } from './objFilter.mjs';
+import { countObj, isJsonObject } from './objChecker.mjs';
+import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange } from './fullScreen.mjs';
+import { calculateMarketcap, compareMarketcap, formatBytes, genFibonacciSeq, getAge, getPercentage, getSimplePerc, ruleOfThree } from './simpleMath.mjs';
+import { addAiMarkerShortcut, diffStrings, diffObjList, safeTextTrim, toTitleCase, toTitleCaseLowerFirst, asyncReplace } from './text.mjs';
+import { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails } from './collision.mjs';
+import { extractMediaId3Tags, parseMediaMetadata, valMediaContentMetadata, valMediaContentMetadataPartial } from './mediaContent.mjs';
+export { multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/basics/index.mjs

@@ -1,11 +1,11 @@
-import { diffArrayList, shuffleArray, arraySortPositions } from './array.mjs';
+import { diffArrayList, shuffleArray, arraySortPositions, multiplyArrayBlocks } from './array.mjs';
 import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, } from './clock.mjs';
 import { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, fetchText, } from './html.mjs';
 import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType } from './objFilter.mjs';
 import { countObj, isJsonObject } from './objChecker.mjs';
 import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, } from './fullScreen.mjs';
 import { calculateMarketcap, compareMarketcap, formatBytes, genFibonacciSeq, getAge, getPercentage, getSimplePerc, ruleOfThree, } from './simpleMath.mjs';
-import { addAiMarkerShortcut, diffStrings, safeTextTrim, toTitleCase, toTitleCaseLowerFirst, asyncReplace, } from './text.mjs';
+import { addAiMarkerShortcut, diffStrings, diffObjList, safeTextTrim, toTitleCase, toTitleCaseLowerFirst, asyncReplace, } from './text.mjs';
 import { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, } from './collision.mjs';
 import { extractMediaId3Tags, parseMediaMetadata, valMediaContentMetadata, valMediaContentMetadataPartial, } from './mediaContent.mjs';
-export { valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+export { multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/dist/v1/basics/mediaContent.cjs

@@ -1,12 +1,18 @@
 'use strict';
 
 /**
+ * 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.
@@ -28,7 +34,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.
@@ -49,7 +55,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
  */
 
 /**
@@ -67,7 +74,8 @@
  * 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
  */
 
 //////////////////////////////////////////////////////////////////
@@ -76,11 +84,11 @@
  * 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.
@@ -88,14 +96,17 @@
  */
 
 /**
+ * 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.
@@ -104,10 +115,34 @@
 
 //////////////////////////////////////////////////////////////////
 
+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>} */
 const _blobCounter = new Map();
 
-/** @returns {MediaContentBase} */
+/**
+ * Returns a new object initialized with the default values for the core media content properties.
+ * @returns {MediaContentBase}
+ */
 const getMediaContentBase = () => ({
   id: '',
   title: '',
@@ -117,7 +152,10 @@ const getMediaContentBase = () => ({
   weight: 1,
 });
 
-/** @returns {MediaContentMetadata} */
+/**
+ * Returns a new object initialized with the default values for the media content metadata properties.
+ * @returns {MediaContentMetadata<PictureDataType>}
+ */
 const getMediaContentMetadata = () => ({
   title: null,
   album: null,
@@ -145,6 +183,11 @@ class MediaLoadingError extends Error {
    * @param {LoadingErrorStage} stage - The stage where the error occurred.
    */
   constructor(message, url, stage) {
+    checkString(message, 'message');
+    checkString(url, 'url');
+    if (typeof stage !== 'string')
+      throw new TypeError(`Expected "stage" to be a string, but received ${typeof stage}.`);
+
     super(message);
     this.name = 'MediaLoadingError';
     this.url = url;
@@ -159,6 +202,8 @@ class MediaLoadingError extends Error {
  * @private
  */
 const generateSimpleHash = async (str) => {
+  checkString(str, 'str');
+
   const msgUint8 = new TextEncoder().encode(str);
   const hashBuffer = await crypto.subtle.digest('SHA-1', msgUint8);
   const hashArray = Array.from(new Uint8Array(hashBuffer));
@@ -171,12 +216,18 @@ 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.
- * @private
  */
 const convertToBlobUrl = (data, format = 'image/jpeg') => {
+  if (!(data instanceof Uint8Array) && typeof data !== 'string') {
+    throw new TypeError(
+      `Expected "data" to be an instance of Uint8Array or a string, but received ${typeof data}.`,
+    );
+  }
+  checkString(format, 'format');
+
   const createBlobCounter = (/** @type {Blob} */ blob) => {
     const url = URL.createObjectURL(blob);
     const blobUrlUsage = _blobCounter.get(url);
@@ -205,10 +256,11 @@ const convertToBlobUrl = (data, format = 'image/jpeg') => {
  * Asynchronous helper to convert a Blob URL back to Base64 (Date URL) at export time.
  * @param {string} url
  * @returns {Promise<string>}
- * @private
  */
 const blobUrlToBase64 = async (url) => {
-  if (typeof url !== 'string' || !url.startsWith('blob:')) return url;
+  checkString(url, 'url');
+
+  if (!url.startsWith('blob:')) return url;
   try {
     const response = await fetch(url);
     const blob = await response.blob();
@@ -226,10 +278,12 @@ const blobUrlToBase64 = async (url) => {
 
 /**
  * Safely revokes Blob URLs to prevent memory leaks from createObjectURL.
- * @param {MediaContent} content
- * @private
+ * @template {PictureDataType} PictureData
+ * @param {MediaContent<PictureData>} content
  */
 const revokeContentUrls = (content) => {
+  checkObject(content, 'content');
+
   if (content && Array.isArray(content.picture)) {
     content.picture.forEach((pic) => {
       if (typeof pic.data === 'string' && pic.data.startsWith('blob:')) {
@@ -248,7 +302,9 @@ const revokeContentUrls = (content) => {
  * @param {boolean} isPartial - If true, properties can be undefined.
  */
 const validateMediaContent = (common, isPartial) => {
-  // Helper to check if the property can be ignored in partial mode
+  checkObject(common, 'common');
+  if (typeof isPartial !== 'boolean') throw new TypeError('Expected "isPartial" to be a boolean.');
+
   const isUndefinedAllowed = (/** @type {any} */ v) => isPartial && typeof v === 'undefined';
 
   const isString = (/** @type {string | null | undefined} */ v) =>
@@ -261,6 +317,7 @@ const validateMediaContent = (common, isPartial) => {
     /** @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)) return true;
     return false;
@@ -293,6 +350,8 @@ const validateMediaContent = (common, isPartial) => {
     !isArray(
       common.picture,
       (value) =>
+        value &&
+        typeof value === 'object' &&
         (typeof value.description === 'undefined' || typeof value.description === 'string') &&
         (typeof value.name === 'undefined' || typeof value.name === 'string') &&
         (typeof value.type === 'undefined' || typeof value.type === 'string') &&
@@ -304,10 +363,11 @@ const validateMediaContent = (common, isPartial) => {
 
   /**
    * 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) {
@@ -322,8 +382,8 @@ const validateMediaContent = (common, isPartial) => {
       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);
 };
 
 /**
@@ -331,30 +391,34 @@ const validateMediaContent = (common, isPartial) => {
  * This ensures that if a property is present, it matches the expected type.
  * @param {ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>} common
  */
-const valMediaContentMetadata = (common) => validateMediaContent(common, false);
+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
  */
-const valMediaContentMetadataPartial = (common) => validateMediaContent(common, true);
+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.
  */
 const extractMediaId3Tags = async (url, parseFile) => {
   // Argument Validation
-  if (typeof url !== 'string')
-    throw new TypeError(`Expected url to be a string, but received ${typeof url}.`);
-  if (typeof parseFile !== 'function')
-    throw new TypeError(`Expected parseFile to be a function, but received ${typeof parseFile}.`);
+  checkString(url, 'url');
+  checkFunction(parseFile, 'parseFile');
 
   try {
     // 1. Download the file from the provided URL
@@ -407,15 +471,16 @@ 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
@@ -449,7 +514,8 @@ const parseMediaMetadata = async (
   source,
   defaultMetadata = {},
   metadata = {},
-  parseFile = (url) => {
+  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 = {},
@@ -459,11 +525,20 @@ const parseMediaMetadata = async (
   if (typeof source !== 'string' && !(source instanceof HTMLMediaElement))
     throw new TypeError('Source must be a string or an HTMLMediaElement.');
 
+  checkObject(defaultMetadata, 'defaultMetadata');
+  checkObject(metadata, 'metadata');
+  checkFunction(parseFile, 'parseFile');
+  checkObject(callbacks, 'callbacks');
+
   if (callbacks.onProgress && typeof callbacks.onProgress !== 'function')
     throw new TypeError('callbacks.onProgress must be a function.');
   if (callbacks.onError && typeof callbacks.onError !== 'function')
     throw new TypeError('callbacks.onError must be a function.');
 
+  if (typeof unknownArtist !== 'string' && typeof unknownArtist !== 'function') {
+    throw new TypeError('unknownArtist must be a string or a function returning a string.');
+  }
+
   /** @type {HTMLMediaElement} */
   let audio;
   /** @type {string} */
@@ -474,6 +549,11 @@ const parseMediaMetadata = async (
    * @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,
@@ -485,6 +565,9 @@ const parseMediaMetadata = async (
   };
 
   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,
@@ -561,7 +644,7 @@ const parseMediaMetadata = async (
     };
 
     // 4. Automatic Metadata Extraction (ID3 Tags)
-    /** @type {Partial<MediaContentMetadata>} */
+    /** @type {Partial<MediaContentMetadata<string>>} */
     let extractedMetadata = {};
     notifyProgress('EXTRACTING_ID3');
     try {
@@ -579,6 +662,7 @@ const parseMediaMetadata = async (
      * @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();
@@ -612,7 +696,7 @@ const parseMediaMetadata = async (
       });
     }
 
-    return /** @type {MediaContent} */ (finalContent);
+    return /** @type {MediaContent<PictureData>} */ (finalContent);
   } catch (err) {
     // If it's already a MediaLoadingError, re-throw it.
     // Otherwise, wrap it.