tiny-essentials 1.28.0 → 1.28.2

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,38 +64,64 @@
  * 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.
  * @property {LoadingErrorStage} stage - The stage where it failed.
  */
 //////////////////////////////////////////////////////////////////
+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: '',
@@ -98,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,
@@ -125,6 +160,10 @@ export 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;
@@ -138,6 +177,7 @@ export class MediaLoadingError extends Error {
  * @private
  */
 export 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));
@@ -149,12 +189,15 @@ 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.
- * @private
  */
 export 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);
@@ -182,10 +225,10 @@ export 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
  */
 export const blobUrlToBase64 = async (url) => {
-    if (typeof url !== 'string' || !url.startsWith('blob:'))
+    checkString(url, 'url');
+    if (!url.startsWith('blob:'))
         return url;
     try {
         const response = await fetch(url);
@@ -204,10 +247,11 @@ export 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
  */
 export 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:')) {
@@ -228,13 +272,16 @@ export 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) => isUndefinedAllowed(v) || typeof v === 'string' || v === null;
     const isNumber = (/** @type {number | null | undefined}} */ v) => isUndefinedAllowed(v) || typeof v === 'number' || v === null;
     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))
@@ -263,7 +310,9 @@ const validateMediaContent = (common, isPartial) => {
         throw new TypeError('Invalid metadata: "composer" must be an array of string.');
     if (!isArray(common.artists, (value) => typeof value === 'string'))
         throw new TypeError('Invalid metadata: "artists" must be an array of string.');
-    if (!isArray(common.picture, (value) => (typeof value.description === 'undefined' || typeof value.description === 'string') &&
+    if (!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') &&
         typeof value.format === 'string' &&
@@ -271,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) {
@@ -287,36 +337,40 @@ 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.
  */
 export 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
         const response = await fetch(url);
@@ -361,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
@@ -399,16 +454,25 @@ 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
     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} */
@@ -418,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,
@@ -428,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,
@@ -492,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 {
@@ -510,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();
@@ -540,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.cjs

@@ -4,20 +4,22 @@
  * Counts the number of elements in an array or the number of properties in an object.
  *
  * @param {Array<*>|Record<string | number | symbol, any>} obj - The array or object to count.
- * @returns {number} - The count of items (array elements or object keys), or `0` if the input is neither an array nor an object.
+ * @returns {number} - The count of items (array elements or object keys).
+ * @throws {TypeError} If the input is neither an array nor a pure object.
  *
  * @example
  * countObj([1, 2, 3]); // 3
  * countObj({ a: 1, b: 2 }); // 2
- * countObj('not an object'); // 0
+ * countObj('not an object'); // Throws TypeError
  */
 function countObj(obj) {
+  if (!Array.isArray(obj) && !isJsonObject(obj))
+    throw new TypeError('Argument must be either an Array or a pure JSON Object.');
+
   // Is Array
   if (Array.isArray(obj)) return obj.length;
   // Object
-  if (isJsonObject(obj)) return Object.keys(obj).length;
-  // Nothing
-  return 0;
+  return Object.keys(obj).length;
 }
 
 /**

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

@@ -2,14 +2,15 @@
  * Counts the number of elements in an array or the number of properties in an object.
  *
  * @param {Array<*>|Record<string | number | symbol, any>} obj - The array or object to count.
- * @returns {number} - The count of items (array elements or object keys), or `0` if the input is neither an array nor an object.
+ * @returns {number} - The count of items (array elements or object keys).
+ * @throws {TypeError} If the input is neither an array nor a pure object.
  *
  * @example
  * countObj([1, 2, 3]); // 3
  * countObj({ a: 1, b: 2 }); // 2
- * countObj('not an object'); // 0
+ * 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).
  *
@@ -25,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/objChecker.mjs

@@ -2,22 +2,22 @@
  * Counts the number of elements in an array or the number of properties in an object.
  *
  * @param {Array<*>|Record<string | number | symbol, any>} obj - The array or object to count.
- * @returns {number} - The count of items (array elements or object keys), or `0` if the input is neither an array nor an object.
+ * @returns {number} - The count of items (array elements or object keys).
+ * @throws {TypeError} If the input is neither an array nor a pure object.
  *
  * @example
  * countObj([1, 2, 3]); // 3
  * countObj({ a: 1, b: 2 }); // 2
- * countObj('not an object'); // 0
+ * countObj('not an object'); // Throws TypeError
  */
 export function countObj(obj) {
+    if (!Array.isArray(obj) && !isJsonObject(obj))
+        throw new TypeError('Argument must be either an Array or a pure JSON Object.');
     // Is Array
     if (Array.isArray(obj))
         return obj.length;
     // Object
-    if (isJsonObject(obj))
-        return Object.keys(obj).length;
-    // Nothing
-    return 0;
+    return Object.keys(obj).length;
 }
 /**
  * Determines whether a given value is a pure JSON object (plain object).

package/dist/v1/basics/objFilter.cjs

@@ -33,26 +33,48 @@ const typeValidator = {
  * If no index is provided, the type is inserted just before 'object' (if it exists), or at the end.
  *
  * @param {ExtendObjType|ExtendObjTypeArray} newItems
- *        - New type validators to be added.
+ * - New type validators to be added.
  * @param {number} [index] - Optional. Position at which to insert each new type. Ignored if the type already exists.
  * @returns {string[]} - A list of successfully added type names.
  *
  * @example
  * extendObjType({
- *   htmlElement2: val => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement
+ * htmlElement2: val => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement
  * });
  *
  * @example
  * extendObjType([
- *   ['alpha', val => typeof val === 'string'],
- *   ['beta', val => Array.isArray(val)]
+ * ['alpha', val => typeof val === 'string'],
+ * ['beta', val => Array.isArray(val)]
  * ]);
  */
 function extendObjType(newItems, index) {
+  if (typeof newItems !== 'object' || newItems === null) {
+    throw new TypeError("Argument 'newItems' must be an object or an array.");
+  }
+
+  if (typeof index !== 'undefined' && typeof index !== 'number') {
+    throw new TypeError("Argument 'index' must be a number.");
+  }
+
   const added = [];
 
   const entries = Array.isArray(newItems) ? newItems : Object.entries(newItems);
-  for (const [key, fn] of entries) {
+
+  for (const entry of entries) {
+    if (!Array.isArray(entry) || entry.length < 2) {
+      throw new TypeError("Each item in 'newItems' array must be a [key, function] pair.");
+    }
+
+    const [key, fn] = entry;
+
+    if (typeof key !== 'string') {
+      throw new TypeError('Validator key must be a string.');
+    }
+    if (typeof fn !== 'function') {
+      throw new TypeError(`Validator for key '${key}' must be a function.`);
+    }
+
     if (!typeValidator.items.hasOwnProperty(key)) {
       // @ts-ignore
       typeValidator.items[key] = fn;
@@ -86,10 +108,17 @@ function extendObjType(newItems, index) {
  *
  * @example
  * reorderObjTypeOrder([
- *   'string', 'number', 'array', 'object'
+ * 'string', 'number', 'array', 'object'
  * ]);
  */
 function reorderObjTypeOrder(newOrder) {
+  if (!Array.isArray(newOrder)) {
+    throw new TypeError("Argument 'newOrder' must be an array of strings.");
+  }
+  if (!newOrder.every((item) => typeof item === 'string')) {
+    throw new TypeError("All elements in 'newOrder' must be strings.");
+  }
+
   const currentOrder = [...typeValidator.order]; // shallow clone
 
   // All keys in newOrder must exist in currentOrder
@@ -147,7 +176,7 @@ const getType = (val) => {
  * @param {*} obj - The object to check or identify.
  * @param {string} [type] - Optional. If provided, checks whether the object matches this type (e.g., "object", "array", "string").
  * @returns {boolean|string|null} - Returns `true` if the type matches, `false` if not,
- *                                   the type string if no type is provided, or `null` if the object is `undefined`.
+ * the type string if no type is provided, or `null` if the object is `undefined`.
  *
  * @example
  * objType([], 'array'); // true
@@ -157,6 +186,10 @@ const getType = (val) => {
  */
 function objType(obj, type) {
   if (typeof obj === 'undefined') return null;
+  if (typeof type !== 'undefined' && typeof type !== 'string') {
+    throw new TypeError("Argument 'type' must be a string.");
+  }
+
   const result = getType(obj);
   if (typeof type === 'string') return result === type.toLowerCase();
   return result;
@@ -239,7 +272,10 @@ extendObjType([
   ],
   [
     'array',
-    /** @param {*} val @returns {val is any[]} */
+    /**
+     * @template {any} Value
+     * @param {*} val @returns {val is Value[]}
+     */
     (val) => Array.isArray(val),
   ],
 ]);
@@ -267,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,
   ],
 ]);
@@ -305,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),
   ],
 ]);