tiny-essentials 1.28.0 → 1.28.1

package/dist/v1/basics/simpleMath.cjs

@@ -36,6 +36,14 @@
  * ruleOfThree.execute(2, 6, 3, true); // → 4
  */
 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;
 }
 
@@ -52,6 +60,11 @@ function ruleOfThree(val1, val2, val3, inverse = false) {
  * getSimplePerc(200, 15); // 30
  */
 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);
 }
 
@@ -66,6 +79,11 @@ function getSimplePerc(price, percentage) {
  * getPercentage(5, 100); // 5
  */
 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;
 }
@@ -78,27 +96,31 @@ function getPercentage(part, total) {
  * @returns {number|null} The age in years, or null if `timeData` is not provided or invalid.
  */
 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;
+  if (typeof timeData !== 'number' && typeof timeData !== 'string' && !(timeData instanceof Date)) {
+    throw new TypeError('timeData must be a number, string, or Date object.');
+  }
 
-    const currentDate = now instanceof Date ? now : new Date();
+  if (now !== null && !(now instanceof Date)) {
+    throw new TypeError('now must be a Date object or null.');
+  }
 
-    let age = currentDate.getFullYear() - birthDate.getFullYear();
+  const birthDate = new Date(timeData);
+  if (Number.isNaN(birthDate.getTime())) return null;
 
-    const currentMonth = currentDate.getMonth();
-    const birthMonth = birthDate.getMonth();
+  const currentDate = now instanceof Date ? now : new Date();
 
-    const currentDay = currentDate.getDate();
-    const birthDay = birthDate.getDate();
+  let age = currentDate.getFullYear() - birthDate.getFullYear();
 
-    // Adjust if birthday hasn't occurred yet this year
-    if (currentMonth < birthMonth || (currentMonth === birthMonth && currentDay < birthDay)) age--;
+  const currentMonth = currentDate.getMonth();
+  const birthMonth = birthDate.getMonth();
 
-    return Math.abs(age);
-  }
+  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 null;
+  return Math.abs(age);
 }
 
 /**
@@ -112,7 +134,7 @@ 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
@@ -124,12 +146,23 @@ function getAge(timeData = 0, now = null) {
  * // → { unit: 'MB', value: 1024 }
  */
 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);
 
@@ -168,8 +201,19 @@ function genFibonacciSeq({
   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)];
 
@@ -192,11 +236,19 @@ function genFibonacciSeq({
  * @returns {number} The calculated price per unit of the asset.
  */
 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 (circulatingSupply <= 0) throw new Error('Circulating supply must be greater than zero.');
+  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 RangeError('Circulating supply must be greater than zero.');
   return originalMarketCap / circulatingSupply;
 }
 
@@ -212,8 +264,12 @@ function calculateMarketcap(originalMarketCap, circulatingSupply) {
  * }}
  */
 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 =

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

@@ -76,7 +76,7 @@ export function getAge(timeData?: number | string | Date, now?: Date | null): nu
  *
  * @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
@@ -87,7 +87,7 @@ export function getAge(timeData?: number | string | Date, now?: Date | null): nu
  * formatBytes(1073741824, 2, 'MB');
  * // → { unit: 'MB', value: 1024 }
  */
-export function formatBytes(bytes: number, decimals?: number | null, maxUnit?: string | null): FormattedByteResult;
+export function formatBytes(bytes: number, decimals?: number | null, maxUnit?: "Bytes" | "KB" | "MB" | "GB" | "TB" | "PB" | "EB" | "ZB" | "YB" | null): FormattedByteResult;
 /**
  * Generates a Fibonacci-like sequence as an array of vectors.
  *

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,12 +4,12 @@
  * @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>;
@@ -79,7 +79,7 @@ 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.
@@ -87,9 +87,71 @@ export function addAiMarkerShortcut({ key, className }?: {
  */
 export function safeTextTrim(text: string, limit: number, safeCutZone?: number): string;
 /**
- * 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 function diffObjList<CompareValue1_1 extends Record<string, any>, CompareValue2_1 extends Record<string, any>>(oldStrings: CompareValue1_1, newStrings: CompareValue2_1): DiffStringsData<CompareValue1_1 & CompareValue2_1>;
+/**
+ * @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.
+ */
+export function diffStrings<CompareValue1_1 extends Record<string, any>, CompareValue2_1 extends Record<string, any>>(oldStrings: CompareValue1_1, newStrings: CompareValue2_1): DiffStringsData<CompareValue1_1 & CompareValue2_1>;
+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>>>;
+};
 //# sourceMappingURL=text.d.mts.map