From acee1b7d79d049bd176dfe6ff72f5fe8168caabb Mon Sep 17 00:00:00 2001
From: devlikepro <waha@devlike.pro>
Date: Wed, 22 Jul 2026 16:12:10 +0700
Subject: [PATCH] chore: timehelper docs

---
 src/utils/timehelper.ts | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/utils/timehelper.ts b/src/utils/timehelper.ts
index 132a3c81..14cfbfae 100644
--- a/src/utils/timehelper.ts
+++ b/src/utils/timehelper.ts
@@ -1,5 +1,15 @@
 /**
- * If value is ms - we convert it to seconds
+ * Both helpers detect the unit by magnitude, using 1e12 as the threshold:
+ * as unix SECONDS 1e12 is year 33658, as unix MILLISECONDS it's Sep 2001 - so any realistic "now-ish"
+ * timestamp is below 1e12 in seconds and above it in milliseconds.
+ */
+
+/**
+ * Normalize a unix timestamp to SECONDS.
+ * Milliseconds get converted (floored), values already in seconds pass through unchanged.
+ *
+ * EnsureSeconds(1784477333) => 1784477333 (already seconds)
+ * EnsureSeconds(1784477333000) => 1784477333 (ms => seconds)
  */
 export function EnsureSeconds(ms: number) {
   if (!ms) {
@@ -10,6 +20,13 @@ export function EnsureSeconds(ms: number) {
   }
   return ms;
 }
+
+/**
+ * Normalize a unix timestamp to MILLISECONDS. Seconds get converted, values already in milliseconds pass through unchanged.
+ *
+ * EnsureMilliseconds(1784477333) => 1784477333000 (seconds => ms)
+ * EnsureMilliseconds(1784477333000) => 1784477333000 (already ms)
+ */
 export function EnsureMilliseconds(seconds: number) {
   if (!seconds) {
     return seconds;