tiny-essentials 1.28.11 → 1.28.12

package/dist/v1/basics/clock.cjs

@@ -1,12 +1,26 @@
 'use strict';
 
+/**
+ * Determines the user's preferred time format (12-hour or 24-hour)
+ * based on the system's locale settings.
+ *
+ * Credits: https://www.reddit.com/r/webdev/comments/1azu87y/comment/ks3mtci/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button
+ *
+ * @returns {12|24} Returns 12 if the user's locale uses a 12-hour cycle, otherwise returns 24.
+ */
+function getUserTimeFormat() {
+  const format = new Intl.DateTimeFormat(undefined, { hour: 'numeric' }).resolvedOptions()
+    .hourCycle;
+  return format?.startsWith('h12') ? 12 : 24;
+}
+
 /**
  * Calculates the time duration between the current time and a given time offset.
  *
  * @param {Date} timeData - The target time as a Date object.
  * @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.
+ * @returns {number} The calculated duration in the specified unit, or `null` if `timeData` is not provided.
  */
 function getTimeDuration(timeData = new Date(), durationType = 'asSeconds', now = null) {
   if (!(timeData instanceof Date)) {
@@ -383,3 +397,4 @@ exports.formatCustomTimer = formatCustomTimer;
 exports.formatDayTimer = formatDayTimer;
 exports.formatTimer = formatTimer;
 exports.getTimeDuration = getTimeDuration;
+exports.getUserTimeFormat = getUserTimeFormat;

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

@@ -1,12 +1,21 @@
+/**
+ * Determines the user's preferred time format (12-hour or 24-hour)
+ * based on the system's locale settings.
+ *
+ * Credits: https://www.reddit.com/r/webdev/comments/1azu87y/comment/ks3mtci/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button
+ *
+ * @returns {12|24} Returns 12 if the user's locale uses a 12-hour cycle, otherwise returns 24.
+ */
+export declare function getUserTimeFormat(): 12 | 24;
 /**
  * Calculates the time duration between the current time and a given time offset.
  *
  * @param {Date} timeData - The target time as a Date object.
  * @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.
+ * @returns {number} The calculated duration in the specified unit, or `null` if `timeData` is not provided.
  */
-export declare function getTimeDuration(timeData?: Date, durationType?: 'asMilliseconds' | 'asSeconds' | 'asMinutes' | 'asHours' | 'asDays', now?: Date | null): number | null;
+export declare function getTimeDuration(timeData?: Date, durationType?: 'asMilliseconds' | 'asSeconds' | 'asMinutes' | 'asHours' | 'asDays', now?: Date | null): number;
 /**
  * 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.

package/dist/v1/basics/clock.mjs

@@ -1,10 +1,23 @@
+/**
+ * Determines the user's preferred time format (12-hour or 24-hour)
+ * based on the system's locale settings.
+ *
+ * Credits: https://www.reddit.com/r/webdev/comments/1azu87y/comment/ks3mtci/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button
+ *
+ * @returns {12|24} Returns 12 if the user's locale uses a 12-hour cycle, otherwise returns 24.
+ */
+export function getUserTimeFormat() {
+    const format = new Intl.DateTimeFormat(undefined, { hour: 'numeric' }).resolvedOptions()
+        .hourCycle;
+    return format?.startsWith('h12') ? 12 : 24;
+}
 /**
  * Calculates the time duration between the current time and a given time offset.
  *
  * @param {Date} timeData - The target time as a Date object.
  * @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.
+ * @returns {number} 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)) {

package/dist/v1/basics/index.cjs

@@ -24,6 +24,7 @@ exports.formatCustomTimer = clock.formatCustomTimer;
 exports.formatDayTimer = clock.formatDayTimer;
 exports.formatTimer = clock.formatTimer;
 exports.getTimeDuration = clock.getTimeDuration;
+exports.getUserTimeFormat = clock.getUserTimeFormat;
 exports.fetchJson = html.fetchJson;
 exports.fetchText = html.fetchText;
 exports.installWindowHiddenScript = html.installWindowHiddenScript;

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

@@ -1,5 +1,5 @@
 import { diffArrayList, shuffleArray, arraySortPositions, multiplyArrayBlocks } from './array.mjs';
-import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration } from './clock.mjs';
+import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, getUserTimeFormat } from './clock.mjs';
 import { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, fetchText } from './html.mjs';
 import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, isObjType, objTypeName } from './objFilter.mjs';
 import { countObj, isJsonObject, isValidObj } from './objChecker.mjs';
@@ -10,5 +10,5 @@ import { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areEl
 import { extractMediaId3Tags, parseMediaMetadata, valMediaContentMetadata, valMediaContentMetadataPartial } from './mediaContent.mjs';
 import { createSingletonTask, waitForTrue } from './promiseUtils.mjs';
 import { browserIs, getBrowserCssPrefix, getBrowserPings, getDuckTyping, isBrowserAgent } from './browserDetector.mjs';
-export { getBrowserPings, isBrowserAgent, getBrowserCssPrefix, getDuckTyping, browserIs, isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, isObjType, objTypeName, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+export { getUserTimeFormat, getBrowserPings, isBrowserAgent, getBrowserCssPrefix, getDuckTyping, browserIs, isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, isObjType, objTypeName, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/basics/index.mjs

@@ -1,5 +1,5 @@
 import { diffArrayList, shuffleArray, arraySortPositions, multiplyArrayBlocks } from './array.mjs';
-import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, } from './clock.mjs';
+import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, getUserTimeFormat, } from './clock.mjs';
 import { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, fetchText, } from './html.mjs';
 import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, isObjType, objTypeName, } from './objFilter.mjs';
 import { countObj, isJsonObject, isValidObj } from './objChecker.mjs';
@@ -10,4 +10,4 @@ import { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areEl
 import { extractMediaId3Tags, parseMediaMetadata, valMediaContentMetadata, valMediaContentMetadataPartial, } from './mediaContent.mjs';
 import { createSingletonTask, waitForTrue } from './promiseUtils.mjs';
 import { browserIs, getBrowserCssPrefix, getBrowserPings, getDuckTyping, isBrowserAgent, } from './browserDetector.mjs';
-export { getBrowserPings, isBrowserAgent, getBrowserCssPrefix, getDuckTyping, browserIs, isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, isObjType, objTypeName, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+export { getUserTimeFormat, getBrowserPings, isBrowserAgent, getBrowserCssPrefix, getDuckTyping, browserIs, isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, isObjType, objTypeName, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/dist/v1/index.cjs

@@ -71,6 +71,7 @@ exports.formatCustomTimer = clock.formatCustomTimer;
 exports.formatDayTimer = clock.formatDayTimer;
 exports.formatTimer = clock.formatTimer;
 exports.getTimeDuration = clock.getTimeDuration;
+exports.getUserTimeFormat = clock.getUserTimeFormat;
 exports.checkObj = objFilter.checkObj;
 exports.cloneObjTypeOrder = objFilter.cloneObjTypeOrder;
 exports.extendObjType = objFilter.extendObjType;

package/dist/v1/index.d.mts

@@ -1,6 +1,6 @@
 import TinyLevelUp from './libs/TinyLevelUp.mjs';
 import { diffArrayList, shuffleArray, arraySortPositions, multiplyArrayBlocks } from './basics/array.mjs';
-import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration } from './basics/clock.mjs';
+import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, getUserTimeFormat } from './basics/clock.mjs';
 import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, checkObj, objTypeName, isObjType } from './basics/objFilter.mjs';
 import { countObj, isJsonObject, isValidObj } from './basics/objChecker.mjs';
 import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange } from './basics/fullScreen.mjs';
@@ -56,5 +56,5 @@ import { createCheckDestroyed } from './libs/utils.mjs';
 import { createSingletonTask, waitForTrue } from './basics/promiseUtils.mjs';
 import TinyDebugger from './libs/TinyDebugger.mjs';
 import { browserIs, getBrowserCssPrefix, getBrowserPings, getDuckTyping, isBrowserAgent } from './basics/browserDetector.mjs';
-export { TinyDebugger, TinyMediaPlayer, TinyRadioFm, TinyClassManager, FuzzySet, MamdaniInferenceSystem, TinyArrayComparator, TinyTextDiffer, TinyAnalogClock, TinyColorValidator, TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, getBrowserPings, isBrowserAgent, getBrowserCssPrefix, getDuckTyping, browserIs, isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, createCheckDestroyed, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, defuzzifyCentroid, trapezoid, diffArrayList, diffStrings, diffObjList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objTypeName, isObjType, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+export { TinyDebugger, TinyMediaPlayer, TinyRadioFm, TinyClassManager, FuzzySet, MamdaniInferenceSystem, TinyArrayComparator, TinyTextDiffer, TinyAnalogClock, TinyColorValidator, TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, getUserTimeFormat, getBrowserPings, isBrowserAgent, getBrowserCssPrefix, getDuckTyping, browserIs, isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, createCheckDestroyed, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, defuzzifyCentroid, trapezoid, diffArrayList, diffStrings, diffObjList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objTypeName, isObjType, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/index.mjs

@@ -1,6 +1,6 @@
 import TinyLevelUp from './libs/TinyLevelUp.mjs';
 import { diffArrayList, shuffleArray, arraySortPositions, multiplyArrayBlocks, } from './basics/array.mjs';
-import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, } from './basics/clock.mjs';
+import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, getUserTimeFormat, } from './basics/clock.mjs';
 import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, checkObj, objTypeName, isObjType, } from './basics/objFilter.mjs';
 import { countObj, isJsonObject, isValidObj } from './basics/objChecker.mjs';
 import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, } from './basics/fullScreen.mjs';
@@ -59,4 +59,4 @@ import { browserIs, getBrowserCssPrefix, getBrowserPings, getDuckTyping, isBrows
 // import TinyHtmlElems from './libs/TinyHtml/index.mjs';
 export { TinyDebugger, TinyMediaPlayer, TinyRadioFm, TinyClassManager, FuzzySet, MamdaniInferenceSystem, TinyArrayComparator, TinyTextDiffer, TinyAnalogClock, 
 // TinyHtmlElems,
-TinyColorValidator, TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, getBrowserPings, isBrowserAgent, getBrowserCssPrefix, getDuckTyping, browserIs, isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, createCheckDestroyed, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, defuzzifyCentroid, trapezoid, diffArrayList, diffStrings, diffObjList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objTypeName, isObjType, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+TinyColorValidator, TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, getUserTimeFormat, getBrowserPings, isBrowserAgent, getBrowserCssPrefix, getDuckTyping, browserIs, isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, createCheckDestroyed, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, defuzzifyCentroid, trapezoid, diffArrayList, diffStrings, diffObjList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objTypeName, isObjType, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/docs/v1/basics/clock.md

@@ -6,6 +6,7 @@ A versatile time utility module for JavaScript that helps you calculate and form
 
 - 🔢 Calculate time differences in various units
 - 🧭 Format durations into clean, readable timer strings
+- 🌍 Locale-aware time cycle detection (12h vs 24h)
 - 🧱 Support for years, months, days, hours, minutes, seconds **and milliseconds**
 - 🎛️ Customizable output with template-based formatting
 - 🛠️ Built-in presets for classic timer formats
@@ -15,6 +16,14 @@ A versatile time utility module for JavaScript that helps you calculate and form
 
 ## 🧠 API Overview
 
+### 🔹 `getUserTimeFormat()`
+
+Detects the user's preferred time format (12-hour or 24-hour) based on the system's locale settings.
+
+**Returns:** `number` — `12` if the user's locale uses a 12-hour cycle, otherwise `24`.
+
+---
+
 ### 🔹 `getTimeDuration(timeData, durationType = 'asSeconds', now = null)`
 
 Calculates how much time remains (or has passed) between now and a given time.
@@ -25,7 +34,7 @@ Calculates how much time remains (or has passed) between now and a given time.
 | `durationType` | `string` | Format to return (`asMilliseconds`, `asSeconds`, `asMinutes`, etc.) |
 | `now`          | `Date`   | Optional custom "now". Defaults to current time.                    |
 
-**Returns:** `number|null` — The duration in the chosen unit.
+**Returns:** `number` — The duration in the chosen unit.
 
 ---
 
@@ -93,15 +102,22 @@ This is useful when you want numeric values to build your own custom formats.
 ## 🧪 Examples
 
 ```js
+// Detect user time preference
+const timeFormat = getUserTimeFormat();
+console.log(timeFormat); // 12 or 24
+
+// Calculate remaining time
 const futureTime = new Date(Date.now() + 10000);
 const secondsLeft = getTimeDuration(futureTime, 'asSeconds');
 
 console.log(formatTimer(secondsLeft)); // e.g. "00:00:09"
 console.log(formatDayTimer(172800 + 3661)); // "2d 01:01:01"
 
+// Custom formatting
 const custom = formatCustomTimer(3600 * 26 + 61, 'days', '{days}d {hours}h {minutes}m {seconds}s');
 console.log(custom); // "1d 2h 1m 1s"
 
+// Detailed breakdown
 const breakdown = breakdownDuration(987654321, 'years');
 console.log(breakdown);
 // {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.28.11",
+  "version": "1.28.12",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "bin": {
     "tiny-essentials-fork": "./TinyFork.mjs"