chore: timehelper docs

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;