tiny-essentials 1.28.0 → 1.28.2

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

@@ -2,11 +2,11 @@
  * Calculates the time duration between the current time and a given time offset.
  *
  * @param {Date} timeData - The target time as a Date object.
- * @param {string} [durationType='asSeconds'] - The type of duration to return. Can be 'asMilliseconds', 'asSeconds', 'asMinutes', 'asHours', 'asDays'.
+ * @param {'asMilliseconds'|'asSeconds'|'asMinutes'|'asHours'|'asDays'} [durationType='asSeconds'] - The type of duration to return.
  * @param {Date|null} [now=null] - The current time as a Date object. Defaults to the current date and time if not provided.
  * @returns {number|null} The calculated duration in the specified unit, or `null` if `timeData` is not provided.
  */
-export function getTimeDuration(timeData?: Date, durationType?: string, now?: Date | null): number | null;
+export declare function getTimeDuration(timeData?: Date, durationType?: 'asMilliseconds' | 'asSeconds' | 'asMinutes' | 'asHours' | 'asDays', now?: Date | null): number | null;
 /**
  * Formats a custom timer string based on total seconds and a detail level.
  * Includes proper reallocation of lower units into higher ones, ensuring consistent hierarchy.
@@ -16,7 +16,7 @@ export function getTimeDuration(timeData?: Date, durationType?: string, now?: Da
  * @param {string} [format='{time}'] - Output template with placeholders like {years}, {months}, {days}, {hours}, {minutes}, {seconds}, {time}, {total}.
  * @returns {string} The formatted timer string.
  */
-export function formatCustomTimer(totalSeconds: number, level?: "seconds" | "minutes" | "hours" | "days" | "months" | "years", format?: string): string;
+export declare function formatCustomTimer(totalSeconds: number, level?: 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years', format?: string): string;
 /**
  * Formats a duration (in seconds) into a timer string showing only hours, minutes, and seconds.
  *
@@ -25,7 +25,7 @@ export function formatCustomTimer(totalSeconds: number, level?: "seconds" | "min
  * @param {number} seconds - The total number of seconds to format.
  * @returns {string} The formatted timer string in "HH:MM:SS" format.
  */
-export function formatTimer(seconds: number): string;
+export declare function formatTimer(seconds: number): string;
 /**
  * Formats a duration (in seconds) into a timer string including days, hours, minutes, and seconds.
  *
@@ -34,31 +34,31 @@ export function formatTimer(seconds: number): string;
  * @param {number} seconds - The total number of seconds to format.
  * @returns {string} The formatted timer string in "Xd HH:MM:SS" format.
  */
-export function formatDayTimer(seconds: number): string;
+export declare function formatDayTimer(seconds: number): string;
 /**
  * Breaks down a duration in milliseconds into its time components.
  *
  * @param {number} totalMs - The total duration in milliseconds.
  * @param {'milliseconds'|'seconds'|'minutes'|'hours'|'days'|'months'|'years'} [level='milliseconds'] - The highest level to calculate and display.
  * @returns {{
- *   years: number|NaN,
- *   months: number|NaN,
- *   days: number|NaN,
- *   hours: number|NaN,
- *   minutes: number|NaN,
- *   seconds: number|NaN,
- *   milliseconds: number|NaN,
- *   total: number|NaN
+ * years: number,
+ * months: number,
+ * days: number,
+ * hours: number,
+ * minutes: number,
+ * seconds: number,
+ * milliseconds: number,
+ * total: number
  * }}
  */
-export function breakdownDuration(totalMs: number, level?: "milliseconds" | "seconds" | "minutes" | "hours" | "days" | "months" | "years"): {
-    years: number | number;
-    months: number | number;
-    days: number | number;
-    hours: number | number;
-    minutes: number | number;
-    seconds: number | number;
-    milliseconds: number | number;
-    total: number | number;
+export declare function breakdownDuration(totalMs: number, level?: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): {
+    years: number;
+    months: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+    total: number;
 };
 //# sourceMappingURL=clock.d.mts.map

package/dist/v1/basics/clock.mjs

@@ -2,31 +2,41 @@
  * Calculates the time duration between the current time and a given time offset.
  *
  * @param {Date} timeData - The target time as a Date object.
- * @param {string} [durationType='asSeconds'] - The type of duration to return. Can be 'asMilliseconds', 'asSeconds', 'asMinutes', 'asHours', 'asDays'.
+ * @param {'asMilliseconds'|'asSeconds'|'asMinutes'|'asHours'|'asDays'} [durationType='asSeconds'] - The type of duration to return.
  * @param {Date|null} [now=null] - The current time as a Date object. Defaults to the current date and time if not provided.
  * @returns {number|null} The calculated duration in the specified unit, or `null` if `timeData` is not provided.
  */
 export function getTimeDuration(timeData = new Date(), durationType = 'asSeconds', now = null) {
-    if (timeData instanceof Date) {
-        const currentTime = now instanceof Date ? now : new Date();
-        /** @type {number} */
-        const diffMs = timeData.getTime() - currentTime.getTime();
-        switch (durationType) {
-            case 'asMilliseconds':
-                return diffMs;
-            case 'asSeconds':
-                return diffMs / 1000;
-            case 'asMinutes':
-                return diffMs / (1000 * 60);
-            case 'asHours':
-                return diffMs / (1000 * 60 * 60);
-            case 'asDays':
-                return diffMs / (1000 * 60 * 60 * 24);
-            default:
-                return diffMs / 1000; // default to seconds
-        }
+    if (!(timeData instanceof Date)) {
+        throw new TypeError("The 'timeData' argument must be an instance of Date.");
+    }
+    if (typeof durationType !== 'string') {
+        throw new TypeError("The 'durationType' argument must be a string.");
+    }
+    const validDurationTypes = ['asMilliseconds', 'asSeconds', 'asMinutes', 'asHours', 'asDays'];
+    if (!validDurationTypes.includes(durationType)) {
+        throw new RangeError(`The 'durationType' must be one of: ${validDurationTypes.join(', ')}.`);
+    }
+    if (now !== null && !(now instanceof Date)) {
+        throw new TypeError("The 'now' argument must be an instance of Date or null.");
+    }
+    const currentTime = now instanceof Date ? now : new Date();
+    /** @type {number} */
+    const diffMs = timeData.getTime() - currentTime.getTime();
+    switch (durationType) {
+        case 'asMilliseconds':
+            return diffMs;
+        case 'asSeconds':
+            return diffMs / 1000;
+        case 'asMinutes':
+            return diffMs / (1000 * 60);
+        case 'asHours':
+            return diffMs / (1000 * 60 * 60);
+        case 'asDays':
+            return diffMs / (1000 * 60 * 60 * 24);
+        default:
+            return diffMs / 1000; // default to seconds
     }
-    return null;
 }
 /**
  * Formats a custom timer string based on total seconds and a detail level.
@@ -38,8 +48,20 @@ export function getTimeDuration(timeData = new Date(), durationType = 'asSeconds
  * @returns {string} The formatted timer string.
  */
 export function formatCustomTimer(totalSeconds, level = 'seconds', format = '{time}') {
-    totalSeconds = Math.max(0, Math.floor(totalSeconds));
+    if (typeof totalSeconds !== 'number' || Number.isNaN(totalSeconds)) {
+        throw new TypeError("The 'totalSeconds' argument must be a valid number.");
+    }
+    if (typeof level !== 'string') {
+        throw new TypeError("The 'level' argument must be a string.");
+    }
     const levels = ['seconds', 'minutes', 'hours', 'days', 'months', 'years'];
+    if (!levels.includes(level)) {
+        throw new RangeError(`The 'level' must be one of: ${levels.join(', ')}.`);
+    }
+    if (typeof format !== 'string') {
+        throw new TypeError("The 'format' argument must be a string.");
+    }
+    totalSeconds = Math.max(0, Math.floor(totalSeconds));
     const index = levels.indexOf(level);
     const include = {
         years: index >= 5,
@@ -51,13 +73,13 @@ export function formatCustomTimer(totalSeconds, level = 'seconds', format = '{ti
     };
     /**
      * @type {{
-     *   years: number|NaN,
-     *   months: number|NaN,
-     *   days: number|NaN,
-     *   hours: number|NaN,
-     *   minutes: number|NaN,
-     *   seconds: number|NaN,
-     *   total: number|NaN
+     * years: number,
+     * months: number,
+     * days: number,
+     * hours: number,
+     * minutes: number,
+     * seconds: number,
+     * total: number
      * }}
      */
     const parts = {
@@ -109,14 +131,14 @@ export function formatCustomTimer(totalSeconds, level = 'seconds', format = '{ti
         parts.seconds = remaining;
     }
     // Calculate total
-    const totalMap = {
-        seconds: include.seconds ? totalSeconds : NaN,
-        minutes: include.minutes ? totalSeconds / 60 : NaN,
-        hours: include.hours ? totalSeconds / 3600 : NaN,
-        days: include.days ? totalSeconds / 86400 : NaN,
-        months: include.months ? parts.years * 12 + parts.months + (parts.days || 0) / 30 : NaN,
-        years: include.years ? parts.years + (parts.months || 0) / 12 + (parts.days || 0) / 365 : NaN,
-    };
+    /** const totalMap = {
+      seconds: include.seconds ? totalSeconds : NaN,
+      minutes: include.minutes ? totalSeconds / 60 : NaN,
+      hours: include.hours ? totalSeconds / 3600 : NaN,
+      days: include.days ? totalSeconds / 86400 : NaN,
+      months: include.months ? parts.years * 12 + parts.months + (parts.days || 0) / 30 : NaN,
+      years: include.years ? parts.years + (parts.months || 0) / 12 + (parts.days || 0) / 365 : NaN,
+    }; */
     parts.total = +totalSeconds.toFixed(2).replace(/\.00$/, '');
     /**
      * Pads a number to ensure it is at least two digits long, using leading zeros if necessary.
@@ -155,6 +177,9 @@ export function formatCustomTimer(totalSeconds, level = 'seconds', format = '{ti
  * @returns {string} The formatted timer string in "HH:MM:SS" format.
  */
 export function formatTimer(seconds) {
+    if (typeof seconds !== 'number' || Number.isNaN(seconds)) {
+        throw new TypeError("The 'seconds' argument must be a valid number.");
+    }
     return formatCustomTimer(seconds, 'hours', '{hours}:{minutes}:{seconds}');
 }
 /**
@@ -166,6 +191,9 @@ export function formatTimer(seconds) {
  * @returns {string} The formatted timer string in "Xd HH:MM:SS" format.
  */
 export function formatDayTimer(seconds) {
+    if (typeof seconds !== 'number' || Number.isNaN(seconds)) {
+        throw new TypeError("The 'seconds' argument must be a valid number.");
+    }
     return formatCustomTimer(seconds, 'days', '{days}d {hours}:{minutes}:{seconds}');
 }
 /**
@@ -174,19 +202,28 @@ export function formatDayTimer(seconds) {
  * @param {number} totalMs - The total duration in milliseconds.
  * @param {'milliseconds'|'seconds'|'minutes'|'hours'|'days'|'months'|'years'} [level='milliseconds'] - The highest level to calculate and display.
  * @returns {{
- *   years: number|NaN,
- *   months: number|NaN,
- *   days: number|NaN,
- *   hours: number|NaN,
- *   minutes: number|NaN,
- *   seconds: number|NaN,
- *   milliseconds: number|NaN,
- *   total: number|NaN
+ * years: number,
+ * months: number,
+ * days: number,
+ * hours: number,
+ * minutes: number,
+ * seconds: number,
+ * milliseconds: number,
+ * total: number
  * }}
  */
 export function breakdownDuration(totalMs, level = 'milliseconds') {
-    totalMs = Math.max(0, Math.floor(totalMs));
+    if (typeof totalMs !== 'number' || Number.isNaN(totalMs)) {
+        throw new TypeError("The 'totalMs' argument must be a valid number.");
+    }
+    if (typeof level !== 'string') {
+        throw new TypeError("The 'level' argument must be a string.");
+    }
     const levels = ['milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'];
+    if (!levels.includes(level)) {
+        throw new RangeError(`The 'level' must be one of: ${levels.join(', ')}.`);
+    }
+    totalMs = Math.max(0, Math.floor(totalMs));
     const index = levels.indexOf(level);
     const include = {
         years: index >= 6,
@@ -251,15 +288,15 @@ export function breakdownDuration(totalMs, level = 'milliseconds') {
         parts.milliseconds = remaining;
     }
     // Totals
-    const totalMap = {
-        milliseconds: include.milliseconds ? totalMs : NaN,
-        seconds: include.seconds ? totalMs / 1000 : NaN,
-        minutes: include.minutes ? totalMs / 60000 : NaN,
-        hours: include.hours ? totalMs / 3600000 : NaN,
-        days: include.days ? totalMs / 86400000 : NaN,
-        months: include.months ? parts.years * 12 + parts.months + (parts.days || 0) / 30 : NaN,
-        years: include.years ? parts.years + (parts.months || 0) / 12 + (parts.days || 0) / 365 : NaN,
-    };
+    /** const totalMap = {
+      milliseconds: include.milliseconds ? totalMs : NaN,
+      seconds: include.seconds ? totalMs / 1000 : NaN,
+      minutes: include.minutes ? totalMs / 60000 : NaN,
+      hours: include.hours ? totalMs / 3600000 : NaN,
+      days: include.days ? totalMs / 86400000 : NaN,
+      months: include.months ? parts.years * 12 + parts.months + (parts.days || 0) / 30 : NaN,
+      years: include.years ? parts.years + (parts.months || 0) / 12 + (parts.days || 0) / 365 : NaN,
+    }; */
     parts.total = +totalMs;
     return parts;
 }