tiny-essentials 1.28.0 → 1.28.2

package/dist/v1/basics/simpleMath.mjs

@@ -34,6 +34,14 @@
  * ruleOfThree.execute(2, 6, 3, true); // → 4
  */
 export function ruleOfThree(val1, val2, val3, inverse = false) {
+    if (typeof val1 !== 'number' || !Number.isFinite(val1))
+        throw new TypeError('val1 must be a finite number.');
+    if (typeof val2 !== 'number' || !Number.isFinite(val2))
+        throw new TypeError('val2 must be a finite number.');
+    if (typeof val3 !== 'number' || !Number.isFinite(val3))
+        throw new TypeError('val3 must be a finite number.');
+    if (typeof inverse !== 'boolean')
+        throw new TypeError('inverse must be a boolean.');
     return inverse ? Number(val1 * val2) / val3 : Number(val3 * val2) / val1;
 }
 /**
@@ -49,6 +57,10 @@ export function ruleOfThree(val1, val2, val3, inverse = false) {
  * getSimplePerc(200, 15); // 30
  */
 export function getSimplePerc(price, percentage) {
+    if (typeof price !== 'number' || !Number.isFinite(price))
+        throw new TypeError('price must be a finite number.');
+    if (typeof percentage !== 'number' || !Number.isFinite(percentage))
+        throw new TypeError('percentage must be a finite number.');
     return price * (percentage / 100);
 }
 /**
@@ -62,6 +74,10 @@ export function getSimplePerc(price, percentage) {
  * getPercentage(5, 100); // 5
  */
 export function getPercentage(part, total) {
+    if (typeof part !== 'number' || !Number.isFinite(part))
+        throw new TypeError('part must be a finite number.');
+    if (typeof total !== 'number' || !Number.isFinite(total))
+        throw new TypeError('total must be a finite number.');
     if (total === 0)
         return 0;
     return (part / total) * 100;
@@ -74,22 +90,25 @@ export function getPercentage(part, total) {
  * @returns {number|null} The age in years, or null if `timeData` is not provided or invalid.
  */
 export function getAge(timeData = 0, now = null) {
-    if (typeof timeData !== 'undefined' && timeData !== null && timeData !== 0) {
-        const birthDate = new Date(timeData);
-        if (Number.isNaN(birthDate.getTime()))
-            return null;
-        const currentDate = now instanceof Date ? now : new Date();
-        let age = currentDate.getFullYear() - birthDate.getFullYear();
-        const currentMonth = currentDate.getMonth();
-        const birthMonth = birthDate.getMonth();
-        const currentDay = currentDate.getDate();
-        const birthDay = birthDate.getDate();
-        // Adjust if birthday hasn't occurred yet this year
-        if (currentMonth < birthMonth || (currentMonth === birthMonth && currentDay < birthDay))
-            age--;
-        return Math.abs(age);
+    if (typeof timeData !== 'number' && typeof timeData !== 'string' && !(timeData instanceof Date)) {
+        throw new TypeError('timeData must be a number, string, or Date object.');
     }
-    return null;
+    if (now !== null && !(now instanceof Date)) {
+        throw new TypeError('now must be a Date object or null.');
+    }
+    const birthDate = new Date(timeData);
+    if (Number.isNaN(birthDate.getTime()))
+        return null;
+    const currentDate = now instanceof Date ? now : new Date();
+    let age = currentDate.getFullYear() - birthDate.getFullYear();
+    const currentMonth = currentDate.getMonth();
+    const birthMonth = birthDate.getMonth();
+    const currentDay = currentDate.getDate();
+    const birthDay = birthDate.getDate();
+    // Adjust if birthday hasn't occurred yet this year
+    if (currentMonth < birthMonth || (currentMonth === birthMonth && currentDay < birthDay))
+        age--;
+    return Math.abs(age);
 }
 /**
  * @typedef {Object} FormattedByteResult
@@ -101,7 +120,7 @@ export function getAge(timeData = 0, now = null) {
  *
  * @param {number} bytes - The number of bytes to format. Must be a non-negative number.
  * @param {number|null} [decimals=null] - The number of decimal places to include in the result. Defaults to null. If negative, it will be treated as 0. If null, no rounding is applied.
- * @param {string|null} [maxUnit=null] - Optional unit limit. If provided, restricts conversion to this unit at most (e.g., 'MB' prevents conversion to 'GB' or higher). Must be one of: 'Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'.
+ * @param {'Bytes'|'KB'|'MB'|'GB'|'TB'|'PB'|'EB'|'ZB'|'YB'|null} [maxUnit=null] - Optional unit limit. If provided, restricts conversion to this unit at most (e.g., 'MB' prevents conversion to 'GB' or higher).
  * @returns {FormattedByteResult} An object with the converted value and its corresponding unit. Returns nulls if input is invalid.
  *
  * @example
@@ -113,12 +132,21 @@ export function getAge(timeData = 0, now = null) {
  * // → { unit: 'MB', value: 1024 }
  */
 export function formatBytes(bytes, decimals = null, maxUnit = null) {
-    if (typeof bytes !== 'number' || bytes < 0)
-        return { unit: null, value: null };
+    if (typeof bytes !== 'number' || !Number.isFinite(bytes) || bytes < 0)
+        throw new TypeError('bytes must be a positive number.');
     if (bytes === 0)
         return { unit: 'Bytes', value: 0 };
+    if (decimals !== null && (typeof decimals !== 'number' || !Number.isFinite(decimals))) {
+        throw new TypeError('decimals must be a number or null.');
+    }
     const k = 1024;
     const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
+    if (maxUnit !== null) {
+        if (typeof maxUnit !== 'string')
+            throw new TypeError('maxUnit must be a string or null.');
+        if (!sizes.includes(maxUnit))
+            throw new RangeError(`maxUnit must be one of: ${sizes.join(', ')}`);
+    }
     const maxIndex = maxUnit && sizes.includes(maxUnit) ? sizes.indexOf(maxUnit) : sizes.length - 1;
     const i = Math.min(Math.floor(Math.log(bytes) / Math.log(k)), maxIndex);
     let value = bytes / Math.pow(k, i);
@@ -149,8 +177,17 @@ export function formatBytes(bytes, decimals = null, maxUnit = null) {
  * @beta
  */
 export function genFibonacciSeq({ baseValues = [0, 1], length = 10, combiner = (a, b) => a + b, } = {}) {
-    if (!Array.isArray(baseValues) || baseValues.length !== 2)
-        throw new Error('baseValues must be an array of exactly two numbers');
+    if (!Array.isArray(baseValues) ||
+        baseValues.length !== 2 ||
+        !baseValues.every((value) => typeof value === 'number')) {
+        throw new Error('baseValues must be an array of exactly two numbers.');
+    }
+    if (typeof length !== 'number' || !Number.isInteger(length)) {
+        throw new RangeError('length must be an integer.');
+    }
+    if (typeof combiner !== 'function') {
+        throw new TypeError('combiner must be a function.');
+    }
     const sequence = [...baseValues.slice(0, 2)];
     for (let i = 2; i < length; i++) {
         const next = combiner(sequence[i - 2], sequence[i - 1], i);
@@ -169,12 +206,16 @@ export function genFibonacciSeq({ baseValues = [0, 1], length = 10, combiner = (
  * @returns {number} The calculated price per unit of the asset.
  */
 export function calculateMarketcap(originalMarketCap, circulatingSupply) {
-    if (Number.isNaN(originalMarketCap) || !Number.isFinite(originalMarketCap))
-        throw new TypeError('Original market cap must be a number.');
-    if (Number.isNaN(circulatingSupply) || !Number.isFinite(circulatingSupply))
-        throw new TypeError('Circulating supply must be a number.');
+    if (typeof originalMarketCap !== 'number' ||
+        Number.isNaN(originalMarketCap) ||
+        !Number.isFinite(originalMarketCap))
+        throw new TypeError('Original market cap must be a finite number.');
+    if (typeof circulatingSupply !== 'number' ||
+        Number.isNaN(circulatingSupply) ||
+        !Number.isFinite(circulatingSupply))
+        throw new TypeError('Circulating supply must be a finite number.');
     if (circulatingSupply <= 0)
-        throw new Error('Circulating supply must be greater than zero.');
+        throw new RangeError('Circulating supply must be greater than zero.');
     return originalMarketCap / circulatingSupply;
 }
 /**
@@ -189,8 +230,10 @@ export function calculateMarketcap(originalMarketCap, circulatingSupply) {
  * }}
  */
 export function compareMarketcap(originalMarketCap, circulatingSupply, newMarketCap) {
-    if (Number.isNaN(newMarketCap) || !Number.isFinite(newMarketCap))
-        throw new TypeError('New market cap must be a number.');
+    if (typeof newMarketCap !== 'number' ||
+        Number.isNaN(newMarketCap) ||
+        !Number.isFinite(newMarketCap))
+        throw new TypeError('New market cap must be a finite number.');
     const originalPrice = calculateMarketcap(originalMarketCap, circulatingSupply);
     const newPrice = typeof newMarketCap === 'number' ? newMarketCap / circulatingSupply : NaN;
     const priceChangePercent = typeof newMarketCap === 'number' ? ((newPrice - originalPrice) / originalPrice) * 100 : NaN;

package/dist/v1/basics/text.cjs

@@ -6,15 +6,25 @@
  * @param {string} str - The input string to perform replacements on.
  * @param {RegExp} regex - The regular expression to match substrings for replacement.
  * @param {Function} asyncFn - An asynchronous function that returns a replacement for each match.
- *                             It receives the same arguments as a standard `replace` callback.
+ * It receives the same arguments as a standard `replace` callback.
  * @returns {Promise<string>} The resulting string with all async replacements applied.
  *
  * @example
  * await asyncReplace("Hello @user1 and @user2!", /@\w+/g, async (mention) => {
- *   return await getUserNameFromMention(mention);
+ * return await getUserNameFromMention(mention);
  * });
  */
 async function asyncReplace(str, regex, asyncFn) {
+  if (typeof str !== 'string') {
+    throw new TypeError(`Expected a string for 'str', but received ${typeof str}`);
+  }
+  if (!(regex instanceof RegExp)) {
+    throw new TypeError(`Expected a RegExp for 'regex', but received ${typeof regex}`);
+  }
+  if (typeof asyncFn !== 'function') {
+    throw new TypeError(`Expected a function for 'asyncFn', but received ${typeof asyncFn}`);
+  }
+
   /**
    * @type {any[]}
    */
@@ -42,6 +52,10 @@ async function asyncReplace(str, regex, asyncFn) {
  * @returns {string} The string converted to title case.
  */
 function toTitleCase(str) {
+  if (typeof str !== 'string') {
+    throw new TypeError(`Expected a string for 'str', but received ${typeof str}`);
+  }
+
   return str.replace(/\w\S*/g, (txt) => txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase());
 }
 
@@ -55,6 +69,10 @@ function toTitleCase(str) {
  * @returns {string} The string converted to title case with the first letter in lowercase.
  */
 function toTitleCaseLowerFirst(str) {
+  if (typeof str !== 'string') {
+    throw new TypeError(`Expected a string for 'str', but received ${typeof str}`);
+  }
+
   const titleCased = str.replace(
     /\w\S*/g,
     (txt) => txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase(),
@@ -101,6 +119,15 @@ function addAiMarkerShortcut({ key = 'a', className = 'detect-made-by-ai' } = {}
       '[AiMarkerShortcut] Environment does not support the DOM. This function must be run in a browser.',
     );
 
+  if (typeof key !== 'string') {
+    throw new TypeError(`Expected a string for 'config.key', but received ${typeof key}`);
+  }
+  if (typeof className !== 'string') {
+    throw new TypeError(
+      `Expected a string for 'config.className', but received ${typeof className}`,
+    );
+  }
+
   /** @type {(this: Document, ev: KeyboardEvent) => any} */
   const keydownEvent = function (event) {
     if (event.ctrlKey && event.altKey && event.key.toLowerCase() === key) {
@@ -128,7 +155,7 @@ function addAiMarkerShortcut({ key = 'a', className = 'detect-made-by-ai' } = {}
  * @param {string} text - The input text to be trimmed.
  * @param {number} limit - The maximum number of characters allowed.
  * @param {number} [safeCutZone=0.6] - A decimal between 0 and 1 representing the minimal acceptable position
- *                                     (as a fraction of `limit`) to cut at a space. Defaults to 0.6.
+ * (as a fraction of `limit`) to cut at a space. Defaults to 0.6.
  * @returns {string} - The trimmed text, possibly ending with an ellipsis ("...").
  * @throws {TypeError} - Throws if `text` is not a string.
  * @throws {TypeError} - Throws if `limit` is not a positive integer.
@@ -162,18 +189,48 @@ function safeTextTrim(text, limit, safeCutZone = 0.6) {
 }
 
 /**
- * Diff two string objects.
- * @param {Record<string,string>} oldStrings
- * @param {Record<string,string>} newStrings
+ * @template {Record<string, any>} CompareValue
+ * @typedef {Object} DiffStringsModifiedValue
+ * @property {CompareValue[keyof CompareValue]} old - The value before the modification.
+ * @property {CompareValue[keyof CompareValue]} new - The new value after the modification.
+ */
+
+/**
+ * @template {Record<string, any>} CompareValue
+ * @typedef {Object} DiffStringsData
+ * @property {Partial<CompareValue>} added - Properties that only exist in the new object.
+ * @property {Partial<CompareValue>} removed - Properties that only existed in the old object.
+ * @property {Partial<Record<keyof CompareValue, DiffStringsModifiedValue<CompareValue>>>} modified - Properties that changed, containing their old and new values.
+ */
+
+/**
+ * Diff two objects.
+ * @template {Record<string, any>} CompareValue1
+ * @template {Record<string, any>} CompareValue2
+ * @param {CompareValue1} oldStrings - The original/old object for comparison.
+ * @param {CompareValue2} newStrings - The new object for comparison.
+ * @returns {DiffStringsData<CompareValue1 & CompareValue2>} An object containing what was added, removed, and modified.
  */
-function diffStrings(oldStrings, newStrings) {
-  /** @type {Record<string,Record<string,string|Record<string,string>>>}} */
+function diffObjList(oldStrings, newStrings) {
+  if (typeof oldStrings !== 'object' || oldStrings === null || Array.isArray(oldStrings)) {
+    throw new TypeError(
+      `Expected an object for 'oldStrings', but received ${oldStrings === null ? 'null' : typeof oldStrings}`,
+    );
+  }
+  if (typeof newStrings !== 'object' || newStrings === null || Array.isArray(newStrings)) {
+    throw new TypeError(
+      `Expected an object for 'newStrings', but received ${newStrings === null ? 'null' : typeof newStrings}`,
+    );
+  }
+
+  /** @type {DiffStringsData<CompareValue1 & CompareValue2>} */
   const changes = { added: {}, removed: {}, modified: {} };
 
   // detect removed and modified
   for (const prop in oldStrings) {
     if (!(prop in newStrings)) {
       changes.removed[prop] = oldStrings[prop];
+      // @ts-ignore
     } else if (oldStrings[prop] !== newStrings[prop]) {
       changes.modified[prop] = { old: oldStrings[prop], new: newStrings[prop] };
     }
@@ -189,32 +246,20 @@ function diffStrings(oldStrings, newStrings) {
   return changes;
 }
 
-/*
-import { useEffect } from "react";
-
-function KeyPressHandler() {
-    useEffect(() => {
-        const handleKeyDown = (event) => {
-            if (event.ctrlKey && event.altKey && event.key.toLowerCase() === "a") {
-                event.preventDefault();
-                document.body.classList.toggle("detect-made-by-ai");
-            }
-        };
-        
-        document.addEventListener("keydown", handleKeyDown);
-        return () => {
-            document.removeEventListener("keydown", handleKeyDown);
-        };
-    }, []);
-
-    return null;
-}
-
-export default KeyPressHandler;
-*/
+/**
+ * Diff two objects.
+ * @template {Record<string, any>} CompareValue1
+ * @template {Record<string, any>} CompareValue2
+ * @param {CompareValue1} oldStrings - The original/old object for comparison.
+ * @param {CompareValue2} newStrings - The new object for comparison.
+ * @returns {DiffStringsData<CompareValue1 & CompareValue2>} An object containing what was added, removed, and modified.
+ * @deprecated Function rename! Use {@link diffObjList} instead.
+ */
+const diffStrings = diffObjList;
 
 exports.addAiMarkerShortcut = addAiMarkerShortcut;
 exports.asyncReplace = asyncReplace;
+exports.diffObjList = diffObjList;
 exports.diffStrings = diffStrings;
 exports.safeTextTrim = safeTextTrim;
 exports.toTitleCase = toTitleCase;

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

@@ -4,15 +4,15 @@
  * @param {string} str - The input string to perform replacements on.
  * @param {RegExp} regex - The regular expression to match substrings for replacement.
  * @param {Function} asyncFn - An asynchronous function that returns a replacement for each match.
- *                             It receives the same arguments as a standard `replace` callback.
+ * It receives the same arguments as a standard `replace` callback.
  * @returns {Promise<string>} The resulting string with all async replacements applied.
  *
  * @example
  * await asyncReplace("Hello @user1 and @user2!", /@\w+/g, async (mention) => {
- *   return await getUserNameFromMention(mention);
+ * return await getUserNameFromMention(mention);
  * });
  */
-export function asyncReplace(str: string, regex: RegExp, asyncFn: Function): Promise<string>;
+export declare function asyncReplace(str: string, regex: RegExp, asyncFn: Function): Promise<string>;
 /**
  * Converts a string to title case where the first letter of each word is capitalized.
  * All other letters are converted to lowercase.
@@ -22,7 +22,7 @@ export function asyncReplace(str: string, regex: RegExp, asyncFn: Function): Pro
  * @param {string} str - The string to be converted to title case.
  * @returns {string} The string converted to title case.
  */
-export function toTitleCase(str: string): string;
+export declare function toTitleCase(str: string): string;
 /**
  * Converts a string to title case where the first letter of each word is capitalized,
  * but the first letter of the entire string is left lowercase.
@@ -32,7 +32,7 @@ export function toTitleCase(str: string): string;
  * @param {string} str - The string to be converted to title case with the first letter in lowercase.
  * @returns {string} The string converted to title case with the first letter in lowercase.
  */
-export function toTitleCaseLowerFirst(str: string): string;
+export declare function toTitleCaseLowerFirst(str: string): string;
 /**
  * Enables a keyboard shortcut to toggle a CSS class on the document body.
  *
@@ -66,9 +66,9 @@ export function toTitleCaseLowerFirst(str: string): string;
  * @param {string} [config.className='detect-made-by-ai'] - The CSS class to toggle on the `<body>` element.
  * @returns {(this: Document, ev: KeyboardEvent) => any} The event handler attached to `document`.
  */
-export function addAiMarkerShortcut({ key, className }?: {
-    key?: string | undefined;
-    className?: string | undefined;
+export declare function addAiMarkerShortcut({ key, className }?: {
+    key?: string;
+    className?: string;
 }): (this: Document, ev: KeyboardEvent) => any;
 /**
  * Trims a text string to a specified character limit, attempting to avoid cutting words in half.
@@ -79,17 +79,67 @@ export function addAiMarkerShortcut({ key, className }?: {
  * @param {string} text - The input text to be trimmed.
  * @param {number} limit - The maximum number of characters allowed.
  * @param {number} [safeCutZone=0.6] - A decimal between 0 and 1 representing the minimal acceptable position
- *                                     (as a fraction of `limit`) to cut at a space. Defaults to 0.6.
+ * (as a fraction of `limit`) to cut at a space. Defaults to 0.6.
  * @returns {string} - The trimmed text, possibly ending with an ellipsis ("...").
  * @throws {TypeError} - Throws if `text` is not a string.
  * @throws {TypeError} - Throws if `limit` is not a positive integer.
  * @throws {TypeError} - Throws if `safeCutZone` is not a number between 0 and 1 (inclusive).
  */
-export function safeTextTrim(text: string, limit: number, safeCutZone?: number): string;
+export declare function safeTextTrim(text: string, limit: number, safeCutZone?: number): string;
+export type DiffStringsModifiedValue<CompareValue extends Record<string, any>> = {
+    /**
+     * - The value before the modification.
+     */
+    old: CompareValue[keyof CompareValue];
+    /**
+     * - The new value after the modification.
+     */
+    new: CompareValue[keyof CompareValue];
+};
+export type DiffStringsData<CompareValue extends Record<string, any>> = {
+    /**
+     * - Properties that only exist in the new object.
+     */
+    added: Partial<CompareValue>;
+    /**
+     * - Properties that only existed in the old object.
+     */
+    removed: Partial<CompareValue>;
+    /**
+     * - Properties that changed, containing their old and new values.
+     */
+    modified: Partial<Record<keyof CompareValue, DiffStringsModifiedValue<CompareValue>>>;
+};
 /**
- * Diff two string objects.
- * @param {Record<string,string>} oldStrings
- * @param {Record<string,string>} newStrings
+ * @template {Record<string, any>} CompareValue
+ * @typedef {Object} DiffStringsModifiedValue
+ * @property {CompareValue[keyof CompareValue]} old - The value before the modification.
+ * @property {CompareValue[keyof CompareValue]} new - The new value after the modification.
  */
-export function diffStrings(oldStrings: Record<string, string>, newStrings: Record<string, string>): Record<string, Record<string, string | Record<string, string>>>;
+/**
+ * @template {Record<string, any>} CompareValue
+ * @typedef {Object} DiffStringsData
+ * @property {Partial<CompareValue>} added - Properties that only exist in the new object.
+ * @property {Partial<CompareValue>} removed - Properties that only existed in the old object.
+ * @property {Partial<Record<keyof CompareValue, DiffStringsModifiedValue<CompareValue>>>} modified - Properties that changed, containing their old and new values.
+ */
+/**
+ * Diff two objects.
+ * @template {Record<string, any>} CompareValue1
+ * @template {Record<string, any>} CompareValue2
+ * @param {CompareValue1} oldStrings - The original/old object for comparison.
+ * @param {CompareValue2} newStrings - The new object for comparison.
+ * @returns {DiffStringsData<CompareValue1 & CompareValue2>} An object containing what was added, removed, and modified.
+ */
+export declare function diffObjList<CompareValue1 extends Record<string, any>, CompareValue2 extends Record<string, any>>(oldStrings: CompareValue1, newStrings: CompareValue2): DiffStringsData<CompareValue1 & CompareValue2>;
+/**
+ * Diff two objects.
+ * @template {Record<string, any>} CompareValue1
+ * @template {Record<string, any>} CompareValue2
+ * @param {CompareValue1} oldStrings - The original/old object for comparison.
+ * @param {CompareValue2} newStrings - The new object for comparison.
+ * @returns {DiffStringsData<CompareValue1 & CompareValue2>} An object containing what was added, removed, and modified.
+ * @deprecated Function rename! Use {@link diffObjList} instead.
+ */
+export declare const diffStrings: typeof diffObjList;
 //# sourceMappingURL=text.d.mts.map

package/dist/v1/basics/text.mjs

@@ -4,15 +4,24 @@
  * @param {string} str - The input string to perform replacements on.
  * @param {RegExp} regex - The regular expression to match substrings for replacement.
  * @param {Function} asyncFn - An asynchronous function that returns a replacement for each match.
- *                             It receives the same arguments as a standard `replace` callback.
+ * It receives the same arguments as a standard `replace` callback.
  * @returns {Promise<string>} The resulting string with all async replacements applied.
  *
  * @example
  * await asyncReplace("Hello @user1 and @user2!", /@\w+/g, async (mention) => {
- *   return await getUserNameFromMention(mention);
+ * return await getUserNameFromMention(mention);
  * });
  */
 export async function asyncReplace(str, regex, asyncFn) {
+    if (typeof str !== 'string') {
+        throw new TypeError(`Expected a string for 'str', but received ${typeof str}`);
+    }
+    if (!(regex instanceof RegExp)) {
+        throw new TypeError(`Expected a RegExp for 'regex', but received ${typeof regex}`);
+    }
+    if (typeof asyncFn !== 'function') {
+        throw new TypeError(`Expected a function for 'asyncFn', but received ${typeof asyncFn}`);
+    }
     /**
      * @type {any[]}
      */
@@ -36,6 +45,9 @@ export async function asyncReplace(str, regex, asyncFn) {
  * @returns {string} The string converted to title case.
  */
 export function toTitleCase(str) {
+    if (typeof str !== 'string') {
+        throw new TypeError(`Expected a string for 'str', but received ${typeof str}`);
+    }
     return str.replace(/\w\S*/g, (txt) => txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase());
 }
 /**
@@ -48,6 +60,9 @@ export function toTitleCase(str) {
  * @returns {string} The string converted to title case with the first letter in lowercase.
  */
 export function toTitleCaseLowerFirst(str) {
+    if (typeof str !== 'string') {
+        throw new TypeError(`Expected a string for 'str', but received ${typeof str}`);
+    }
     const titleCased = str.replace(/\w\S*/g, (txt) => txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase());
     return titleCased.charAt(0).toLowerCase() + titleCased.slice(1);
 }
@@ -87,6 +102,12 @@ export function toTitleCaseLowerFirst(str) {
 export function addAiMarkerShortcut({ key = 'a', className = 'detect-made-by-ai' } = {}) {
     if (typeof HTMLElement === 'undefined')
         throw new Error('[AiMarkerShortcut] Environment does not support the DOM. This function must be run in a browser.');
+    if (typeof key !== 'string') {
+        throw new TypeError(`Expected a string for 'config.key', but received ${typeof key}`);
+    }
+    if (typeof className !== 'string') {
+        throw new TypeError(`Expected a string for 'config.className', but received ${typeof className}`);
+    }
     /** @type {(this: Document, ev: KeyboardEvent) => any} */
     const keydownEvent = function (event) {
         if (event.ctrlKey && event.altKey && event.key.toLowerCase() === key) {
@@ -110,7 +131,7 @@ export function addAiMarkerShortcut({ key = 'a', className = 'detect-made-by-ai'
  * @param {string} text - The input text to be trimmed.
  * @param {number} limit - The maximum number of characters allowed.
  * @param {number} [safeCutZone=0.6] - A decimal between 0 and 1 representing the minimal acceptable position
- *                                     (as a fraction of `limit`) to cut at a space. Defaults to 0.6.
+ * (as a fraction of `limit`) to cut at a space. Defaults to 0.6.
  * @returns {string} - The trimmed text, possibly ending with an ellipsis ("...").
  * @throws {TypeError} - Throws if `text` is not a string.
  * @throws {TypeError} - Throws if `limit` is not a positive integer.
@@ -139,17 +160,40 @@ export function safeTextTrim(text, limit, safeCutZone = 0.6) {
     return result;
 }
 /**
- * Diff two string objects.
- * @param {Record<string,string>} oldStrings
- * @param {Record<string,string>} newStrings
+ * @template {Record<string, any>} CompareValue
+ * @typedef {Object} DiffStringsModifiedValue
+ * @property {CompareValue[keyof CompareValue]} old - The value before the modification.
+ * @property {CompareValue[keyof CompareValue]} new - The new value after the modification.
+ */
+/**
+ * @template {Record<string, any>} CompareValue
+ * @typedef {Object} DiffStringsData
+ * @property {Partial<CompareValue>} added - Properties that only exist in the new object.
+ * @property {Partial<CompareValue>} removed - Properties that only existed in the old object.
+ * @property {Partial<Record<keyof CompareValue, DiffStringsModifiedValue<CompareValue>>>} modified - Properties that changed, containing their old and new values.
  */
-export function diffStrings(oldStrings, newStrings) {
-    /** @type {Record<string,Record<string,string|Record<string,string>>>}} */
+/**
+ * Diff two objects.
+ * @template {Record<string, any>} CompareValue1
+ * @template {Record<string, any>} CompareValue2
+ * @param {CompareValue1} oldStrings - The original/old object for comparison.
+ * @param {CompareValue2} newStrings - The new object for comparison.
+ * @returns {DiffStringsData<CompareValue1 & CompareValue2>} An object containing what was added, removed, and modified.
+ */
+export function diffObjList(oldStrings, newStrings) {
+    if (typeof oldStrings !== 'object' || oldStrings === null || Array.isArray(oldStrings)) {
+        throw new TypeError(`Expected an object for 'oldStrings', but received ${oldStrings === null ? 'null' : typeof oldStrings}`);
+    }
+    if (typeof newStrings !== 'object' || newStrings === null || Array.isArray(newStrings)) {
+        throw new TypeError(`Expected an object for 'newStrings', but received ${newStrings === null ? 'null' : typeof newStrings}`);
+    }
+    /** @type {DiffStringsData<CompareValue1 & CompareValue2>} */
     const changes = { added: {}, removed: {}, modified: {} };
     // detect removed and modified
     for (const prop in oldStrings) {
         if (!(prop in newStrings)) {
             changes.removed[prop] = oldStrings[prop];
+            // @ts-ignore
         }
         else if (oldStrings[prop] !== newStrings[prop]) {
             changes.modified[prop] = { old: oldStrings[prop], new: newStrings[prop] };
@@ -163,26 +207,13 @@ export function diffStrings(oldStrings, newStrings) {
     }
     return changes;
 }
-/*
-import { useEffect } from "react";
-
-function KeyPressHandler() {
-    useEffect(() => {
-        const handleKeyDown = (event) => {
-            if (event.ctrlKey && event.altKey && event.key.toLowerCase() === "a") {
-                event.preventDefault();
-                document.body.classList.toggle("detect-made-by-ai");
-            }
-        };
-        
-        document.addEventListener("keydown", handleKeyDown);
-        return () => {
-            document.removeEventListener("keydown", handleKeyDown);
-        };
-    }, []);
-
-    return null;
-}
-
-export default KeyPressHandler;
-*/
+/**
+ * Diff two objects.
+ * @template {Record<string, any>} CompareValue1
+ * @template {Record<string, any>} CompareValue2
+ * @param {CompareValue1} oldStrings - The original/old object for comparison.
+ * @param {CompareValue2} newStrings - The new object for comparison.
+ * @returns {DiffStringsData<CompareValue1 & CompareValue2>} An object containing what was added, removed, and modified.
+ * @deprecated Function rename! Use {@link diffObjList} instead.
+ */
+export const diffStrings = diffObjList;

package/dist/v1/build/ColorSafeStringify.d.mts

@@ -1,3 +1,3 @@
-export { ColorSafeStringify };
 import ColorSafeStringify from '../libs/ColorSafeStringify.mjs';
+export { ColorSafeStringify };
 //# sourceMappingURL=ColorSafeStringify.d.mts.map

package/dist/v1/build/TinyAdvancedRaffle.d.mts

@@ -1,3 +1,3 @@
-export { TinyAdvancedRaffle };
 import TinyAdvancedRaffle from '../libs/TinyAdvancedRaffle.mjs';
+export { TinyAdvancedRaffle };
 //# sourceMappingURL=TinyAdvancedRaffle.d.mts.map

package/dist/v1/build/TinyAfterScrollWatcher.d.mts

@@ -1,3 +1,3 @@
-export { TinyAfterScrollWatcher };
 import TinyAfterScrollWatcher from '../libs/TinyAfterScrollWatcher.mjs';
+export { TinyAfterScrollWatcher };
 //# sourceMappingURL=TinyAfterScrollWatcher.d.mts.map

package/dist/v1/build/TinyAnalogClock.d.mts

@@ -1,3 +1,3 @@
-export { TinyAnalogClock };
 import TinyAnalogClock from '../libs/TinyAnalogClock.mjs';
+export { TinyAnalogClock };
 //# sourceMappingURL=TinyAnalogClock.d.mts.map

package/dist/v1/build/TinyArrayComparator.d.mts

@@ -1,3 +1,3 @@
-export { TinyArrayComparator };
 import TinyArrayComparator from '../libs/TinyArrayComparator.mjs';
+export { TinyArrayComparator };
 //# sourceMappingURL=TinyArrayComparator.d.mts.map

package/dist/v1/build/TinyArrayPaginator.d.mts

@@ -1,3 +1,3 @@
-export { TinyArrayPaginator };
 import TinyArrayPaginator from '../libs/TinyArrayPaginator.mjs';
+export { TinyArrayPaginator };
 //# sourceMappingURL=TinyArrayPaginator.d.mts.map

package/dist/v1/build/TinyClassManager.d.mts

@@ -1,3 +1,3 @@
-export { TinyClassManager };
 import TinyClassManager from '../libs/TinyClassManager.mjs';
+export { TinyClassManager };
 //# sourceMappingURL=TinyClassManager.d.mts.map