tiny-essentials 1.28.0 → 1.28.1

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|NaN,
+     * months: number|NaN,
+     * days: number|NaN,
+     * hours: number|NaN,
+     * minutes: number|NaN,
+     * seconds: number|NaN,
+     * total: number|NaN
      * }}
      */
     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|NaN,
+ * months: number|NaN,
+ * days: number|NaN,
+ * hours: number|NaN,
+ * minutes: number|NaN,
+ * seconds: number|NaN,
+ * milliseconds: number|NaN,
+ * total: number|NaN
  * }}
  */
 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;
 }

package/dist/v1/basics/deprecated/html.cjs

@@ -0,0 +1,246 @@
+'use strict';
+
+var html = require('../html.cjs');
+var objChecker = require('../objChecker.cjs');
+
+/**
+ * @typedef {Object} FetchTemplateOptions
+ * @property {string} [method="GET"] - HTTP method to use (GET, POST, etc.).
+ * @property {any} [body] - Request body (only for methods like POST, PUT).
+ * @property {number} [timeout=0] - Timeout in milliseconds (ignored if signal is provided).
+ * @property {number} [retries=0] - Number of retry attempts (ignored if signal is provided).
+ * @property {Headers|Record<string, *>} [headers={}] - Additional headers.
+ * @property {AbortSignal|null} [signal] - External AbortSignal; disables timeout and retries.
+ * @property {import('../html.mjs').FetchOnProgressResult} [onProgress] - Track the load progress.
+ * @deprecated
+ */
+
+/**
+ * @param {string} url - The full URL to fetch data from.
+ * @param {FetchTemplateOptions} [options] - Optional settings.
+ * @returns {Promise<Response>} Result data.
+ * @throws {Error} Throws if fetch fails, times out.
+ */
+async function fetchTemplate(url, options = {}) {
+  if (options !== null && typeof options !== 'object') {
+    throw new TypeError('The "options" argument must be an object.');
+  }
+
+  const {
+    method = 'GET',
+    body,
+    timeout = 0,
+    retries = 0,
+    headers = {},
+    signal = null,
+    onProgress,
+  } = options;
+
+  if (
+    typeof url !== 'string' ||
+    (!url.startsWith('../') &&
+      !url.startsWith('./') &&
+      !url.startsWith('/') &&
+      !url.startsWith('https://') &&
+      !url.startsWith('http://'))
+  )
+    throw new Error('Invalid URL: must be a valid http or https address.');
+
+  if (typeof method !== 'string' || !method.trim())
+    throw new Error('Invalid method: must be a non-empty string.');
+
+  if (headers !== null && typeof headers !== 'object') {
+    throw new TypeError('The "headers" option must be an object.');
+  }
+
+  if (signal !== null && !(signal instanceof AbortSignal)) {
+    throw new TypeError('The "signal" option must be an instance of AbortSignal.');
+  }
+
+  if (onProgress !== undefined && typeof onProgress !== 'function') {
+    throw new TypeError('The "onProgress" option must be a function.');
+  }
+
+  if (!signal) {
+    if (
+      typeof timeout !== 'number' ||
+      !Number.isFinite(timeout) ||
+      Number.isNaN(timeout) ||
+      timeout < 0
+    )
+      throw new Error('Invalid timeout: must be a positive number.');
+
+    if (
+      typeof retries !== 'number' ||
+      !Number.isFinite(retries) ||
+      Number.isNaN(retries) ||
+      retries < 0
+    )
+      throw new Error('Invalid retries: must be a positive number.');
+  }
+
+  const attempts = signal ? 1 : retries + 1;
+  /** @type {Error|null} */
+  let lastError = null;
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const controller = signal ? null : new AbortController();
+    const localSignal = signal || (controller?.signal ?? null);
+    const timer =
+      !signal && timeout && controller ? setTimeout(() => controller.abort(), timeout) : null;
+
+    try {
+      const response = await fetch(url, {
+        method: method.toUpperCase(),
+        headers: {
+          Accept: 'application/json',
+          ...headers,
+        },
+        body: body !== undefined ? (objChecker.isJsonObject(body) ? JSON.stringify(body) : body) : undefined,
+        signal: localSignal,
+      });
+
+      if (timer) clearTimeout(timer);
+
+      if (!response.ok) throw new Error(`HTTP error: ${response.status} ${response.statusText}`);
+
+      // If onProgress is not provided or body is null, return original response
+      if (!onProgress) return response;
+      return html.trackFetchProgress(response, onProgress);
+    } catch (err) {
+      lastError = /** @type {Error} */ (err);
+      if (signal) break; // if an external signal came, it does not retry
+      if (attempt < retries)
+        await new Promise((resolve) => setTimeout(resolve, 300 * (attempt + 1)));
+    }
+  }
+
+  throw new Error(
+    `Failed to fetch JSON from "${url}"${lastError ? `: ${lastError.message}` : '.'}`,
+  );
+}
+
+/**
+ * Loads and parses a JSON from a remote URL using Fetch API.
+ *
+ * @param {string} url - The full URL to fetch JSON from.
+ * @param {FetchTemplateOptions} [options] - Optional settings.
+ * @returns {Promise<any[] | Record<string | number | symbol, unknown>>} Parsed JSON object.
+ * @throws {Error} Throws if fetch fails, times out, or returns invalid JSON.
+ * @deprecated
+ */
+async function fetchJson(url, options) {
+  if (typeof url !== 'string') {
+    return Promise.reject(new TypeError('The "url" argument must be a string.'));
+  }
+  if (options !== undefined && (options === null || typeof options !== 'object')) {
+    return Promise.reject(new TypeError('The "options" argument must be an object.'));
+  }
+
+  return new Promise((resolve, reject) => {
+    fetchTemplate(url, options)
+      .then(async (res) => {
+        const contentType = res.headers.get('content-type') || '';
+        if (!contentType.includes('application/json'))
+          throw new Error(`Unexpected content-type: ${contentType}`);
+
+        const data = await res.json();
+
+        if (!Array.isArray(data) && !objChecker.isJsonObject(data))
+          throw new Error('Received invalid data instead of valid JSON.');
+
+        return resolve(data);
+      })
+      .catch(reject);
+  });
+}
+
+/**
+ * Loads a remote file as a Blob using Fetch API.
+ *
+ * @param {string} url - The full URL to fetch the file from.
+ * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
+ * @param {FetchTemplateOptions} [options] - Optional fetch options.
+ * @returns {Promise<Blob>} - The fetched file as a Blob.
+ * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
+ * @deprecated
+ */
+async function fetchBlob(url, allowedMimeTypes, options) {
+  if (typeof url !== 'string') {
+    return Promise.reject(new TypeError('The "url" argument must be a string.'));
+  }
+  if (allowedMimeTypes !== undefined && !Array.isArray(allowedMimeTypes)) {
+    return Promise.reject(
+      new TypeError('The "allowedMimeTypes" argument must be an array of strings.'),
+    );
+  }
+  if (options !== undefined && (options === null || typeof options !== 'object')) {
+    return Promise.reject(new TypeError('The "options" argument must be an object.'));
+  }
+
+  return new Promise((resolve, reject) => {
+    fetchTemplate(url, options)
+      .then(async (res) => {
+        const contentType = res.headers.get('content-type') || '';
+
+        if (
+          Array.isArray(allowedMimeTypes) &&
+          allowedMimeTypes.length > 0 &&
+          !allowedMimeTypes.some((type) => contentType.includes(type))
+        ) {
+          throw new Error(`Blocked MIME type: ${contentType}`);
+        }
+
+        const data = await res.blob();
+        return resolve(data);
+      })
+      .catch(reject);
+  });
+}
+
+/**
+ * Loads a remote file as a text using Fetch API.
+ *
+ * @param {string} url - The full URL to fetch the file from.
+ * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
+ * @param {FetchTemplateOptions} [options] - Optional fetch options.
+ * @returns {Promise<string>} - The fetched file as a text.
+ * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
+ * @deprecated
+ */
+async function fetchText(url, allowedMimeTypes, options) {
+  if (typeof url !== 'string') {
+    return Promise.reject(new TypeError('The "url" argument must be a string.'));
+  }
+  if (allowedMimeTypes !== undefined && !Array.isArray(allowedMimeTypes)) {
+    return Promise.reject(
+      new TypeError('The "allowedMimeTypes" argument must be an array of strings.'),
+    );
+  }
+  if (options !== undefined && (options === null || typeof options !== 'object')) {
+    return Promise.reject(new TypeError('The "options" argument must be an object.'));
+  }
+
+  return new Promise((resolve, reject) => {
+    fetchTemplate(url, options)
+      .then(async (res) => {
+        const contentType = res.headers.get('content-type') || '';
+
+        if (
+          Array.isArray(allowedMimeTypes) &&
+          allowedMimeTypes.length > 0 &&
+          !allowedMimeTypes.some((type) => contentType.includes(type))
+        ) {
+          throw new Error(`Blocked MIME type: ${contentType}`);
+        }
+
+        const data = await res.text();
+        return resolve(data);
+      })
+      .catch(reject);
+  });
+}
+
+exports.fetchBlob = fetchBlob;
+exports.fetchJson = fetchJson;
+exports.fetchText = fetchText;

package/dist/v1/basics/deprecated/html.d.mts

@@ -0,0 +1,63 @@
+/**
+ * Loads and parses a JSON from a remote URL using Fetch API.
+ *
+ * @param {string} url - The full URL to fetch JSON from.
+ * @param {FetchTemplateOptions} [options] - Optional settings.
+ * @returns {Promise<any[] | Record<string | number | symbol, unknown>>} Parsed JSON object.
+ * @throws {Error} Throws if fetch fails, times out, or returns invalid JSON.
+ * @deprecated
+ */
+export function fetchJson(url: string, options?: FetchTemplateOptions): Promise<any[] | Record<string | number | symbol, unknown>>;
+/**
+ * Loads a remote file as a Blob using Fetch API.
+ *
+ * @param {string} url - The full URL to fetch the file from.
+ * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
+ * @param {FetchTemplateOptions} [options] - Optional fetch options.
+ * @returns {Promise<Blob>} - The fetched file as a Blob.
+ * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
+ * @deprecated
+ */
+export function fetchBlob(url: string, allowedMimeTypes?: string[], options?: FetchTemplateOptions): Promise<Blob>;
+/**
+ * Loads a remote file as a text using Fetch API.
+ *
+ * @param {string} url - The full URL to fetch the file from.
+ * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
+ * @param {FetchTemplateOptions} [options] - Optional fetch options.
+ * @returns {Promise<string>} - The fetched file as a text.
+ * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
+ * @deprecated
+ */
+export function fetchText(url: string, allowedMimeTypes?: string[], options?: FetchTemplateOptions): Promise<string>;
+export type FetchTemplateOptions = {
+    /**
+     * - HTTP method to use (GET, POST, etc.).
+     */
+    method?: string | undefined;
+    /**
+     * - Request body (only for methods like POST, PUT).
+     */
+    body?: any;
+    /**
+     * - Timeout in milliseconds (ignored if signal is provided).
+     */
+    timeout?: number | undefined;
+    /**
+     * - Number of retry attempts (ignored if signal is provided).
+     */
+    retries?: number | undefined;
+    /**
+     * - Additional headers.
+     */
+    headers?: Headers | Record<string, any> | undefined;
+    /**
+     * - External AbortSignal; disables timeout and retries.
+     */
+    signal?: AbortSignal | null | undefined;
+    /**
+     * - Track the load progress.
+     */
+    onProgress?: import("../html.mjs").FetchOnProgressResult | undefined;
+};
+//# sourceMappingURL=html.d.mts.map