Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

5.4 KB
Raw Blame
/**
 * Time formatting utility functions
 * Unified handling of timestamp and ISO format time display
 */
import type { Locale } from "@/i18n/translations"

// Partial with a lookup fallback: distributions may replace @/i18n/translations
// with a widened Locale union, and any unmapped locale is itself a BCP 47 tag.
const displayDateLocales: Partial<Record<Locale, string>> = {
  en: "en-US",
  zh: "zh-CN",
}

/** Formats a non-blank, parseable display-date string, returning empty text for invalid input. */
export function formatDisplayDate(
  value: unknown,
  locale: Locale,
  options: Intl.DateTimeFormatOptions,
): string {
  if (typeof value !== "string" || value.trim() === "") return ""

  const date = new Date(value)
  if (!Number.isFinite(date.getTime())) return ""

  return new Intl.DateTimeFormat(displayDateLocales[locale] ?? locale, options).format(date)
}

/**
 * Normalizes various timestamp formats (seconds, milliseconds, numeric strings, ISO strings)
 * to a standard millisecond timestamp.
 * @param ts The timestamp to normalize
 * @returns Timestamp in milliseconds
 */
export function normalizeTimestampMs(ts?: string | number | Date | null): number {
  // Checked for exact absence, not truthiness: epoch zero (`0`) is a valid,
  // if unlikely, timestamp - a `!ts` check would collapse it into "now" the
  // same way it does undefined/null/"", silently discarding a real value.
  //
  // Deliberately NOT special-casing NaN/Infinity here (a prior version of
  // this function did, then a PR review caught that it was a regression):
  // this function's callers (formatTime, getTimeDuration) already guard
  // against an invalid result via `isNaN(date.getTime())` - new Date(NaN)
  // and new Date(Infinity) both produce an actually-invalid Date, which
  // those checks correctly treat as "malformed input" and fall back to a
  // safe default. Converting NaN/Infinity into Date.now() here instead would
  // make a malformed timestamp look like a perfectly valid "just now" to
  // every caller, defeating that existing downstream safety net. Callers
  // that need non-finite values to look like "absent" for their own UI
  // purposes (e.g. progress-panel.tsx's hasTimestamp) should filter them out
  // themselves before ever calling this function, as that one already does.
  if (ts === undefined || ts === null || ts === '') return Date.now()
  if (ts instanceof Date) return ts.getTime()

  if (typeof ts === 'string') {
    const num = Number(ts)
    // If it's a valid number string (not empty), treat as numeric timestamp
    if (!isNaN(num) && ts.trim() !== '') {
      return num < 1e10 ? num * 1000 : num
    }
    // Otherwise try parsing as date string
    const parsedMs = new Date(ts).getTime()
    return isNaN(parsedMs) ? Date.now() : parsedMs
  }

  if (typeof ts === 'number') {
    return ts < 1e10 ? ts * 1000 : ts
  }

  return Date.now()
}

/**
 * Format time to local time string
 * @param timestamp Timestamp (seconds or milliseconds) or ISO string
 * @param format Output format: 'time' | 'date' | 'datetime'
 * @returns Formatted time string
 */
export function formatTime(
  timestamp: string | number | null | undefined,
  format: 'time' | 'date' | 'datetime' = 'time'
): string {
  if (!timestamp) {
    return ''
  }

  try {
    const date = new Date(normalizeTimestampMs(timestamp))

    if (isNaN(date.getTime())) {
      return String(timestamp)
    }

    switch (format) {
      case 'time':
        return date.toLocaleTimeString()
      case 'date':
        return date.toLocaleDateString()
      case 'datetime':
        return date.toLocaleString()
      default:
        return date.toLocaleTimeString()
    }
  } catch {
    return String(timestamp)
  }
}

/**
 * Calculate time duration
 * @param start Start time (timestamp or ISO string)
 * @param end End time (timestamp or ISO string)
 * @returns Time duration (milliseconds)
 */
export function getTimeDuration(
  start: string | number | null | undefined,
  end: string | number | null | undefined
): number {
  if (!start || !end) {
    return 0
  }

  try {
    const startDate = new Date(normalizeTimestampMs(start))
    const endDate = new Date(normalizeTimestampMs(end))

    if (isNaN(startDate.getTime()) || isNaN(endDate.getTime())) {
      return 0
    }

    return endDate.getTime() - startDate.getTime()
  } catch {
    return 0
  }
}

/**
 * Format time duration
 * @param duration Time duration (milliseconds)
 * @returns Formatted time string (e.g., 1h 30m 25s)
 */
export function formatDuration(duration: number): string {
  if (duration <= 0) {
    return '0s'
  }

  const seconds = Math.floor(duration / 1000)
  const minutes = Math.floor(seconds / 60)
  const hours = Math.floor(minutes / 60)
  const days = Math.floor(hours / 24)

  const parts: string[] = []

  if (days > 0) {
    parts.push(`${days}d`)
  }
  if (hours % 24 > 0) {
    parts.push(`${hours % 24}h`)
  }
  if (minutes % 60 > 0) {
    parts.push(`${minutes % 60}m`)
  }
  if (seconds % 60 > 0) {
    parts.push(`${seconds % 60}s`)
  }

  return parts.join(' ') || '0s'
}

/**
 * Get current timestamp (seconds)
 * @returns Current timestamp
 */
export function getCurrentTimestamp(): number {
  return Math.floor(Date.now() / 1000)
}

/**
 * Check if time is expired
 * @param timestamp Timestamp (seconds)
 * @param seconds Expiration time (seconds)
 * @returns Whether it is expired
 */
export function isExpired(timestamp: number, seconds: number): boolean {
  return getCurrentTimestamp() - timestamp > seconds
}