@poolzin/pool-bot 2026.2.0 → 2026.2.2

package/dist/infra/format-time/format-datetime.js

@@ -0,0 +1,79 @@
+/**
+ * Centralized date/time formatting utilities.
+ *
+ * All formatters are timezone-aware, using Intl.DateTimeFormat.
+ * Consolidates duplicated formatUtcTimestamp / formatZonedTimestamp / resolveExplicitTimezone
+ * that previously lived in envelope.ts and session-updates.ts.
+ */
+/**
+ * Validate an IANA timezone string. Returns the string if valid, undefined otherwise.
+ */
+export function resolveTimezone(value) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: value }).format(new Date());
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Format a Date as a UTC timestamp string.
+ *
+ * Without seconds: `2024-01-15T14:30Z`
+ * With seconds:    `2024-01-15T14:30:05Z`
+ */
+export function formatUtcTimestamp(date, options) {
+    const yyyy = String(date.getUTCFullYear()).padStart(4, "0");
+    const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(date.getUTCDate()).padStart(2, "0");
+    const hh = String(date.getUTCHours()).padStart(2, "0");
+    const min = String(date.getUTCMinutes()).padStart(2, "0");
+    if (!options?.displaySeconds) {
+        return `${yyyy}-${mm}-${dd}T${hh}:${min}Z`;
+    }
+    const sec = String(date.getUTCSeconds()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd}T${hh}:${min}:${sec}Z`;
+}
+/**
+ * Format a Date with timezone display using Intl.DateTimeFormat.
+ *
+ * Without seconds: `2024-01-15 14:30 EST`
+ * With seconds:    `2024-01-15 14:30:05 EST`
+ *
+ * Returns undefined if Intl formatting fails.
+ */
+export function formatZonedTimestamp(date, options) {
+    const intlOptions = {
+        timeZone: options?.timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        hourCycle: "h23",
+        timeZoneName: "short",
+    };
+    if (options?.displaySeconds) {
+        intlOptions.second = "2-digit";
+    }
+    const parts = new Intl.DateTimeFormat("en-US", intlOptions).formatToParts(date);
+    const pick = (type) => parts.find((part) => part.type === type)?.value;
+    const yyyy = pick("year");
+    const mm = pick("month");
+    const dd = pick("day");
+    const hh = pick("hour");
+    const min = pick("minute");
+    const sec = options?.displaySeconds ? pick("second") : undefined;
+    const tz = [...parts]
+        .toReversed()
+        .find((part) => part.type === "timeZoneName")
+        ?.value?.trim();
+    if (!yyyy || !mm || !dd || !hh || !min) {
+        return undefined;
+    }
+    if (options?.displaySeconds && sec) {
+        return `${yyyy}-${mm}-${dd} ${hh}:${min}:${sec}${tz ? ` ${tz}` : ""}`;
+    }
+    return `${yyyy}-${mm}-${dd} ${hh}:${min}${tz ? ` ${tz}` : ""}`;
+}

package/dist/infra/format-time/format-duration.js

@@ -0,0 +1,81 @@
+export function formatDurationSeconds(ms, options = {}) {
+    if (!Number.isFinite(ms)) {
+        return "unknown";
+    }
+    const decimals = options.decimals ?? 1;
+    const unit = options.unit ?? "s";
+    const seconds = Math.max(0, ms) / 1000;
+    const fixed = seconds.toFixed(Math.max(0, decimals));
+    const trimmed = fixed.replace(/\.0+$/, "").replace(/(\.\d*[1-9])0+$/, "$1");
+    return unit === "seconds" ? `${trimmed} seconds` : `${trimmed}s`;
+}
+/** Precise decimal-seconds output: "500ms" or "1.23s". Input is milliseconds. */
+export function formatDurationPrecise(ms, options = {}) {
+    if (!Number.isFinite(ms)) {
+        return "unknown";
+    }
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    return formatDurationSeconds(ms, {
+        decimals: options.decimals ?? 2,
+        unit: options.unit ?? "s",
+    });
+}
+/**
+ * Compact compound duration: "500ms", "45s", "2m5s", "1h30m".
+ * With `spaced`: "45s", "2m 5s", "1h 30m".
+ * Omits trailing zero components: "1m" not "1m 0s", "2h" not "2h 0m".
+ * Returns undefined for null/undefined/non-finite/non-positive input.
+ */
+export function formatDurationCompact(ms, options) {
+    if (ms == null || !Number.isFinite(ms) || ms <= 0) {
+        return undefined;
+    }
+    if (ms < 1000) {
+        return `${Math.round(ms)}ms`;
+    }
+    const sep = options?.spaced ? " " : "";
+    const totalSeconds = Math.round(ms / 1000);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours >= 24) {
+        const days = Math.floor(hours / 24);
+        const remainingHours = hours % 24;
+        return remainingHours > 0 ? `${days}d${sep}${remainingHours}h` : `${days}d`;
+    }
+    if (hours > 0) {
+        return minutes > 0 ? `${hours}h${sep}${minutes}m` : `${hours}h`;
+    }
+    if (minutes > 0) {
+        return seconds > 0 ? `${minutes}m${sep}${seconds}s` : `${minutes}m`;
+    }
+    return `${seconds}s`;
+}
+/**
+ * Rounded single-unit duration for display: "500ms", "5s", "3m", "2h", "5d".
+ * Returns fallback string for null/undefined/non-finite input.
+ */
+export function formatDurationHuman(ms, fallback = "n/a") {
+    if (ms == null || !Number.isFinite(ms) || ms < 0) {
+        return fallback;
+    }
+    if (ms < 1000) {
+        return `${Math.round(ms)}ms`;
+    }
+    const sec = Math.round(ms / 1000);
+    if (sec < 60) {
+        return `${sec}s`;
+    }
+    const min = Math.round(sec / 60);
+    if (min < 60) {
+        return `${min}m`;
+    }
+    const hr = Math.round(min / 60);
+    if (hr < 24) {
+        return `${hr}h`;
+    }
+    const day = Math.round(hr / 24);
+    return `${day}d`;
+}

package/dist/infra/format-time/format-relative.js

@@ -0,0 +1,80 @@
+/**
+ * Centralized relative-time formatting utilities.
+ *
+ * Consolidates 7+ scattered implementations (formatAge, formatAgeShort, formatAgo,
+ * formatRelativeTime, formatElapsedTime) into two functions:
+ *
+ * - `formatTimeAgo(durationMs)` -- format a duration as "5m ago" / "5m" (for known elapsed time)
+ * - `formatRelativeTimestamp(epochMs)` -- format an epoch timestamp relative to now (handles future)
+ */
+/**
+ * Format a duration (in ms) as a human-readable relative time.
+ *
+ * Input: how many milliseconds ago something happened.
+ *
+ * With suffix (default):  "just now", "5m ago", "3h ago", "2d ago"
+ * Without suffix:         "0s", "5m", "3h", "2d"
+ */
+export function formatTimeAgo(durationMs, options) {
+    const suffix = options?.suffix !== false;
+    const fallback = options?.fallback ?? "unknown";
+    if (durationMs == null || !Number.isFinite(durationMs) || durationMs < 0) {
+        return fallback;
+    }
+    const totalSeconds = Math.round(durationMs / 1000);
+    const minutes = Math.round(totalSeconds / 60);
+    if (minutes < 1) {
+        return suffix ? "just now" : `${totalSeconds}s`;
+    }
+    if (minutes < 60) {
+        return suffix ? `${minutes}m ago` : `${minutes}m`;
+    }
+    const hours = Math.round(minutes / 60);
+    if (hours < 48) {
+        return suffix ? `${hours}h ago` : `${hours}h`;
+    }
+    const days = Math.round(hours / 24);
+    return suffix ? `${days}d ago` : `${days}d`;
+}
+/**
+ * Format an epoch timestamp relative to now.
+ *
+ * Handles both past ("5m ago") and future ("in 5m") timestamps.
+ * Optionally falls back to a short date for timestamps older than 7 days.
+ */
+export function formatRelativeTimestamp(timestampMs, options) {
+    const fallback = options?.fallback ?? "n/a";
+    if (timestampMs == null || !Number.isFinite(timestampMs)) {
+        return fallback;
+    }
+    const diff = Date.now() - timestampMs;
+    const absDiff = Math.abs(diff);
+    const isPast = diff >= 0;
+    const sec = Math.round(absDiff / 1000);
+    if (sec < 60) {
+        return isPast ? "just now" : "in <1m";
+    }
+    const min = Math.round(sec / 60);
+    if (min < 60) {
+        return isPast ? `${min}m ago` : `in ${min}m`;
+    }
+    const hr = Math.round(min / 60);
+    if (hr < 48) {
+        return isPast ? `${hr}h ago` : `in ${hr}h`;
+    }
+    const day = Math.round(hr / 24);
+    if (!options?.dateFallback || day <= 7) {
+        return isPast ? `${day}d ago` : `in ${day}d`;
+    }
+    // Fall back to short date display for old timestamps
+    try {
+        return new Intl.DateTimeFormat("en-US", {
+            month: "short",
+            day: "numeric",
+            ...(options.timezone ? { timeZone: options.timezone } : {}),
+        }).format(new Date(timestampMs));
+    }
+    catch {
+        return `${day}d ago`;
+    }
+}