DateTime Operations

/**
 * Creates a DateTime instance with timezone support
 * @param input - Date input (string, number, Date, moment, or DateTime)
 * @param formatInput - Format for parsing input string
 * @param zone - Target timezone
 * @returns DateTime instance
 */
function dateTime(input?: DateTimeInput, formatInput?: FormatInput, zone?: TimeZone): DateTime;

/**
 * Creates a Moment.js compatible DateTime instance
 * @param input - Date input
 * @param formatInput - Format for parsing
 * @param zone - Target timezone  
 * @returns DateTime with moment.js compatibility
 */
function dateTimeAsMoment(input?: DateTimeInput, formatInput?: FormatInput, zone?: TimeZone): DateTime;

/**
 * Creates DateTime for specific timezone
 * @param zone - Target timezone
 * @param input - Date input
 * @param formatInput - Format for parsing
 * @returns DateTime in specified timezone
 */
function dateTimeForTimeZone(zone: TimeZone, input?: DateTimeInput, formatInput?: FormatInput): DateTime;

/**
 * Converts input to UTC DateTime
 * @param input - Date input
 * @param formatInput - Format for parsing
 * @returns UTC DateTime instance
 */
function toUtc(input?: DateTimeInput, formatInput?: FormatInput): DateTime;

/**
 * Creates duration object
 * @param input - Duration input (number or string)
 * @param unit - Duration unit
 * @returns Duration instance
 */
function toDuration(input?: DurationInput, unit?: DurationUnit): DateTimeDuration;

import { dateTime, toUtc, toDuration } from "@grafana/data";

// Create DateTime instances
const now = dateTime();
const specific = dateTime('2023-12-25T10:30:00Z');
const withTimezone = dateTime('2023-12-25 10:30:00', 'YYYY-MM-DD HH:mm:ss', 'America/New_York');

// Convert to UTC
const utcTime = toUtc('2023-12-25T10:30:00+02:00');

// Create durations
const fiveMinutes = toDuration(5, 'minutes');
const twoHours = toDuration('2h');

/**
 * Checks if value is a DateTime instance
 * @param value - Value to check
 * @returns True if value is DateTime
 */
function isDateTime(value: any): value is DateTime;

/**
 * Checks if value is valid DateTime input
 * @param value - Value to check
 * @returns True if value can be converted to DateTime
 */
function isDateTimeInput(value: any): value is DateTimeInput;

/**
 * Sets global locale for DateTime operations
 * @param locale - Locale identifier or configuration
 */
function setLocale(locale: string | DateTimeLocale): void;

/**
 * Gets current locale setting
 * @returns Current locale identifier
 */
function getLocale(): string;

/**
 * Gets locale data for current locale
 * @returns Locale data object
 */
function getLocaleData(): DateTimeLocale;

/**
 * Sets timezone resolver function
 * @param resolver - Function to resolve timezone
 */
function setTimeZoneResolver(resolver: TimeZoneResolver): void;

/**
 * Gets timezone information
 * @param timeZone - Optional timezone identifier
 * @returns Current or specified timezone
 */
function getTimeZone(timeZone?: TimeZone): TimeZone;

/**
 * Formats timezone for user-friendly display
 * @param timeZone - Timezone to format
 * @returns Human-readable timezone name
 */
function timeZoneFormatUserFriendly(timeZone: TimeZone): string;

/**
 * Gets timezone zone information
 * @param timeZone - Timezone identifier
 * @returns Zone information object
 */
function getZone(timeZone: string): TimeZoneInfo;

/**
 * Gets all available timezones
 * @returns Array of timezone identifiers
 */
function getTimeZones(): string[];

/**
 * Gets timezones grouped by region
 * @returns Grouped timezone object
 */
function getTimeZoneGroups(): GroupedTimeZones;

/**
 * Gets detailed timezone information
 * @param timeZone - Timezone identifier
 * @returns Detailed timezone info
 */
function getTimeZoneInfo(timeZone: string): TimeZoneInfo;

/**
 * Gets timezone abbreviation
 * @param timeZone - Timezone identifier
 * @param dateTime - DateTime for abbreviation context
 * @returns Timezone abbreviation (e.g., "PST", "EDT")
 */
function timeZoneAbbrevation(timeZone: TimeZone, dateTime?: DateTime): string;

/**
 * Gets weekday index for a day name
 * @param day - Day name or DateTime
 * @returns Weekday index (0 = Sunday, 1 = Monday, etc.)
 */
function getWeekdayIndex(day: string | DateTime): number;

/**
 * Gets weekday index by English day name
 * @param name - English day name ('Sunday', 'Monday', etc.)
 * @returns Weekday index
 */
function getWeekdayIndexByEnglishName(name: string): number;

/**
 * Sets the start day of the week
 * @param day - Day to start week (0 = Sunday, 1 = Monday, etc.)
 */
function setWeekStart(day: number): void;

/**
 * Formats DateTime with specified options
 * @param dateTime - DateTime to format
 * @param options - Formatting options
 * @returns Formatted date string
 */
function dateTimeFormat(dateTime: DateTime, options?: DateTimeOptionsWithFormat): string;

/**
 * Formats DateTime as ISO string
 * @param dateTime - DateTime to format
 * @param options - ISO formatting options
 * @returns ISO formatted string
 */
function dateTimeFormatISO(dateTime: DateTime, options?: DateTimeOptions): string;

/**
 * Formats DateTime as relative time (time ago)
 * @param dateTime - DateTime to format
 * @param options - Time ago formatting options
 * @returns Relative time string (e.g., "2 hours ago")
 */
function dateTimeFormatTimeAgo(dateTime: DateTime, options?: DateTimeOptions): string;

/**
 * Formats DateTime with timezone abbreviation
 * @param dateTime - DateTime to format
 * @param options - Formatting options
 * @returns Formatted string with timezone abbreviation
 */
function dateTimeFormatWithAbbrevation(dateTime: DateTime, options?: DateTimeOptionsWithFormat): string;

/**
 * Gets local time format configuration
 * @param options - Format options
 * @returns Local time format
 */
function localTimeFormat(options?: DateTimeOptions): string;

/**
 * Parses DateTime from string with options
 * @param value - String to parse
 * @param options - Parsing options including format and timezone
 * @returns Parsed DateTime instance
 */
function dateTimeParse(value: string, options?: DateTimeOptionsWhenParsing): DateTime;

/**
 * Converts interval to abbreviated duration string
 * @param interval - Interval in milliseconds
 * @returns Abbreviated duration (e.g., "5m", "2h", "1d")
 */
function intervalToAbbreviatedDurationString(interval: number): string;

/**
 * Parses duration string to milliseconds
 * @param duration - Duration string (e.g., "5m", "2h", "1d")
 * @returns Duration in milliseconds
 */
function parseDuration(duration: string): number;

/**
 * Reverse parses duration from milliseconds to string
 * @param duration - Duration in milliseconds
 * @returns Duration string
 */
function reverseParseDuration(duration: number): string;

/**
 * Adds duration to a date
 * @param date - Base date
 * @param duration - Duration to add
 * @returns New date with duration added
 */
function addDurationToDate(date: DateTime, duration: DateTimeDuration): DateTime;

/**
 * Converts duration to milliseconds
 * @param duration - Duration object
 * @returns Duration in milliseconds
 */
function durationToMilliseconds(duration: DateTimeDuration): number;

/**
 * Checks if date is valid
 * @param date - Date to validate
 * @returns True if date is valid
 */
function isValidDate(date: any): boolean;

/**
 * Checks if duration is valid
 * @param duration - Duration to validate
 * @returns True if duration is valid
 */
function isValidDuration(duration: any): boolean;

/**
 * Checks if Go-style duration is valid
 * @param duration - Go duration string (e.g., "5m30s")
 * @returns True if valid Go duration
 */
function isValidGoDuration(duration: string): boolean;

/**
 * Checks if Grafana duration format is valid
 * @param duration - Grafana duration string
 * @returns True if valid Grafana duration
 */
function isValidGrafanaDuration(duration: string): boolean;

/**
 * System date formats configuration
 */
const systemDateFormats: SystemDateFormatSettings;

/**
 * System date formats state
 */
interface SystemDateFormatsState {
  fullDate: string;
  interval: {
    millisecond: string;
    second: string;
    minute: string;
    hour: string;
    day: string;
    month: string;
    year: string;
  };
  useBrowserLocale: boolean;
}

/**
 * Date math utilities namespace
 * Provides functions for date arithmetic and parsing
 */
namespace dateMath {
  /** Parse date math expressions like "now-5m" */
  export function parse(text: string, roundUp?: boolean): DateTime | undefined;
  /** Check if string is date math expression */
  export function isDateTime(value: any): boolean;
  /** Parse date math to absolute time */
  export function parseDateMath(mathString: string, time: DateTime): DateTime | undefined;
}

/**
 * Range utilities namespace  
 * Provides functions for time range operations
 */
namespace rangeUtil {
  /** Convert relative time to absolute range */
  export function convertRawToRange(raw: RawTimeRange): TimeRange;
  /** Check if time range is absolute */
  export function isRelativeTimeRange(range: TimeRange): boolean;
  /** Get time range for visualization */
  export function timeRangeForUrl(range: TimeRange): string;
}

/**
 * Main DateTime interface
 */
interface DateTime {
  /** Add time to current DateTime */
  add(amount?: DurationInput, unit?: DurationUnit): DateTime;
  /** Subtract time from current DateTime */
  subtract(amount?: DurationInput, unit?: DurationUnit): DateTime;
  /** Start of time period */
  startOf(unit: DurationUnit): DateTime;
  /** End of time period */
  endOf(unit: DurationUnit): DateTime;
  /** Format DateTime to string */
  format(format?: string): string;
  /** Get timezone offset in minutes */
  utcOffset(): number;
  /** Convert to different timezone */
  tz(zone?: TimeZone): DateTime;
  /** Check if before another DateTime */
  isBefore(other: DateTimeInput): boolean;
  /** Check if after another DateTime */
  isAfter(other: DateTimeInput): boolean;
  /** Check if same as another DateTime */
  isSame(other: DateTimeInput, unit?: DurationUnit): boolean;
  /** Get as Unix timestamp */
  unix(): number;
  /** Get as milliseconds since epoch */
  valueOf(): number;
  /** Convert to native Date */
  toDate(): Date;
  /** Convert to ISO string */
  toISOString(): string;
  /** Get locale */
  locale(): string;
  /** Set locale */
  locale(locale: string): DateTime;
}

/**
 * Duration interface
 */
interface DateTimeDuration {
  /** Get duration in specified unit */
  as(unit: DurationUnit): number;
  /** Get duration in milliseconds */
  asMilliseconds(): number;
  /** Get duration in seconds */
  asSeconds(): number;
  /** Get duration in minutes */
  asMinutes(): number;
  /** Get duration in hours */
  asHours(): number;
  /** Get duration in days */
  asDays(): number;
  /** Add duration to this duration */
  add(amount: DurationInput, unit?: DurationUnit): DateTimeDuration;
  /** Subtract duration from this duration */
  subtract(amount: DurationInput, unit?: DurationUnit): DateTimeDuration;
  /** Get humanized duration string */
  humanize(): string;
}

/**
 * DateTime input types
 */
type DateTimeInput = string | number | Date | DateTime | null | undefined;
type FormatInput = string | undefined;
type DurationInput = string | number | DateTimeDuration;
type DurationUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years';

/**
 * Timezone types
 */
type TimeZone = string | 'browser' | 'utc' | undefined;
type TimeZoneBrowser = 'browser';
type TimeZoneUtc = 'utc';
type DefaultTimeZone = TimeZoneBrowser | TimeZoneUtc;

/**
 * DateTime options
 */
interface DateTimeOptions {
  timeZone?: TimeZone;
}

interface DateTimeOptionsWithFormat extends DateTimeOptions {
  format?: string;
  defaultWithMS?: boolean;
}

interface DateTimeOptionsWhenParsing extends DateTimeOptions {
  format?: string | string[];
  strict?: boolean;
}

/**
 * Locale configuration
 */
interface DateTimeLocale {
  firstDayOfWeek?: number;
  weekdays?: string[];
  weekdaysShort?: string[];
  weekdaysMin?: string[];
  months?: string[];
  monthsShort?: string[];
  longDateFormat?: { [key: string]: string };
  relativeTime?: { [key: string]: string };
  meridiem?: (hour: number, minute: number, isLowercase: boolean) => string;
  calendar?: { [key: string]: string };
}

/**
 * Timezone information
 */
interface TimeZoneInfo {
  name: string;
  zone: string;
  countries: TimeZoneCountry[];
}

interface TimeZoneCountry {
  name: string;
  code: string;
}

interface GroupedTimeZones {
  [region: string]: TimeZoneInfo[];
}

/**
 * System date format settings
 */
interface SystemDateFormatSettings {
  fullDate: string;
  interval: {
    millisecond: string;
    second: string;
    minute: string;
    hour: string;
    day: string;
    month: string;
    year: string;
  };
  useBrowserLocale: boolean;
}

/**
 * Built-in format types
 */
type DateTimeBuiltinFormat = 
  | 'YYYY-MM-DD HH:mm:ss'
  | 'YYYY-MM-DD'
  | 'MM/DD/YYYY'
  | 'DD/MM/YYYY'
  | 'HH:mm:ss'
  | 'HH:mm'
  | 'MM-DD HH:mm'
  | 'YYYY-MM'
  | 'YY-MM-DD'
  | string;

/**
 * Timezone resolver function type
 */
type TimeZoneResolver = () => TimeZone;

/**
 * Constants
 */
const ISO_8601 = 'YYYY-MM-DDTHH:mm:ssZ';

/**
 * Internal timezone constants
 */
enum InternalTimeZones {
  default = '',
  localBrowser = 'browser',
  utc = 'utc'
}