Time Operations

/**
 * Calendar intervals for date/time calculations
 */
const timeMillisecond: TimeInterval;
const timeSecond: TimeInterval;
const timeMinute: TimeInterval;
const timeHour: TimeInterval;
const timeDay: TimeInterval;
const timeWeek: TimeInterval;
const timeSunday: TimeInterval;  // Week starting Sunday
const timeMonday: TimeInterval;  // Week starting Monday
const timeMonth: TimeInterval;
const timeYear: TimeInterval;

/**
 * UTC time intervals (same as above but in UTC)
 */
const utcMillisecond: TimeInterval;
const utcSecond: TimeInterval;
const utcMinute: TimeInterval;
const utcHour: TimeInterval;
const utcDay: TimeInterval;
const utcWeek: TimeInterval;
const utcSunday: TimeInterval;
const utcMonday: TimeInterval;
const utcMonth: TimeInterval;
const utcYear: TimeInterval;

interface TimeInterval {
  /** Round date down to interval boundary */
  (date: Date): Date;
  /** Round date down to interval boundary */
  floor(date: Date): Date;
  /** Round date up to interval boundary */
  ceil(date: Date): Date;
  /** Round date to nearest interval boundary */
  round(date: Date): Date;
  /** Offset date by specified number of intervals */
  offset(date: Date, step: number): Date;
  /** Generate array of dates from start to stop (exclusive) */
  range(start: Date, stop: Date, step?: number): Date[];
  /** Create filtered version of this interval */
  filter(test: (date: Date) => boolean): TimeInterval;
  /** Create interval that occurs every n instances of this interval */
  every(step: number): TimeInterval;
  /** Count number of intervals between start and end */
  count(start: Date, end: Date): number;
}

import { timeDay, timeMonth, timeYear, utcDay } from "d3";

// Floor to day boundary
const now = new Date();
const startOfDay = timeDay(now);

// Generate date ranges
const dailyTicks = timeDay.range(
  new Date(2023, 0, 1),  // Jan 1, 2023
  new Date(2023, 0, 8)   // Jan 8, 2023
);
// [2023-01-01, 2023-01-02, 2023-01-03, ...]

// Monthly intervals
const monthlyTicks = timeMonth.range(
  new Date(2023, 0, 1),
  new Date(2024, 0, 1)
);

// Count intervals
const daysBetween = timeDay.count(
  new Date(2023, 0, 1),
  new Date(2023, 0, 8)
); // 7

// Every 3 days
const everyThreeDays = timeDay.every(3);
const sparseRange = everyThreeDays.range(
  new Date(2023, 0, 1),
  new Date(2023, 0, 15)
);

/**
 * Create custom time interval
 * @param floor - Function to round date down to interval boundary
 * @param offset - Function to offset date by specified step
 * @param count - Function to count intervals between dates
 * @param field - Optional function to extract field value for filtering
 * @returns Custom TimeInterval instance
 */
function timeInterval(
  floor: (date: Date) => void,
  offset: (date: Date, step: number) => void,
  count?: (start: Date, end: Date) => number,
  field?: (date: Date) => number
): TimeInterval;

import { timeInterval } from "d3";

// Custom 15-minute interval
const time15Minute = timeInterval(
  date => {
    const minutes = Math.floor(date.getMinutes() / 15) * 15;
    date.setMinutes(minutes, 0, 0);
  },
  (date, step) => {
    date.setMinutes(date.getMinutes() + step * 15);
  },
  (start, end) => {
    return Math.floor((end.getTime() - start.getTime()) / (15 * 60000));
  }
);

// Use custom interval
const quarter = time15Minute(new Date()); // Round to 15-minute boundary
const range = time15Minute.range(
  new Date(2023, 0, 1, 9, 0),   // 9:00 AM
  new Date(2023, 0, 1, 12, 0)   // 12:00 PM
);

/**
 * Create a time formatter from a specifier string
 * @param specifier - Time format specifier (strftime-like)
 * @returns Function that formats dates according to specifier
 */
function timeFormat(specifier: string): (date: Date) => string;

/**
 * Create a time parser from a specifier string
 * @param specifier - Time format specifier
 * @returns Function that parses strings into dates
 */
function timeParse(specifier: string): (dateString: string) => Date | null;

/**
 * Create a UTC time formatter
 * @param specifier - Time format specifier
 * @returns Function that formats dates in UTC
 */
function utcFormat(specifier: string): (date: Date) => string;

/**
 * Create a UTC time parser
 * @param specifier - Time format specifier  
 * @returns Function that parses strings as UTC dates
 */
function utcParse(specifier: string): (dateString: string) => Date | null;

import { timeFormat, timeParse } from "d3";

// Common formats
const formatTime = timeFormat("%B %d, %Y");
formatTime(new Date(2023, 0, 15)); // "January 15, 2023"

const formatISO = timeFormat("%Y-%m-%d");
formatISO(new Date(2023, 0, 15)); // "2023-01-15"

const formatShort = timeFormat("%m/%d/%y");
formatShort(new Date(2023, 0, 15)); // "01/15/23"

// Parsing
const parseTime = timeParse("%m/%d/%Y");
const date = parseTime("01/15/2023"); // Date object

const parseISO = timeParse("%Y-%m-%d");
const isoDate = parseISO("2023-01-15");

// Date components
"%Y"    // Full year (e.g., 2023)
"%y"    // 2-digit year (e.g., 23)
"%m"    // Month as number (01-12)
"%B"    // Full month name (e.g., January)
"%b"    // Abbreviated month (e.g., Jan)
"%d"    // Day of month (01-31)
"%e"    // Day of month, space-padded (1-31)
"%A"    // Full weekday name (e.g., Sunday)
"%a"    // Abbreviated weekday (e.g., Sun)
"%w"    // Weekday as number (0-6, Sunday = 0)
"%j"    // Day of year (001-366)
"%U"    // Week number, Sunday first (00-53)
"%W"    // Week number, Monday first (00-53)

// Time components  
"%H"    // Hour, 24-hour (00-23)
"%I"    // Hour, 12-hour (01-12)
"%M"    // Minute (00-59)
"%S"    // Second (00-59)
"%L"    // Milliseconds (000-999)
"%f"    // Microseconds (000000-999999)
"%p"    // AM/PM
"%Z"    // Time zone name

// Literals
"%%"    // Literal percent sign

/**
 * Create parser that tries multiple format specifiers
 * @param specifiers - Array of format specifier strings to try
 * @returns Parser function that attempts each format
 */
function timeParse(...specifiers: string[]): (dateString: string) => Date | null;

/**
 * Create UTC parser that tries multiple format specifiers
 * @param specifiers - Array of format specifier strings to try
 * @returns Parser function that attempts each format in UTC
 */
function utcParse(...specifiers: string[]): (dateString: string) => Date | null;

/**
 * Create locale with custom time formatting rules
 * @param definition - Locale definition for time formatting
 * @returns TimeLocale object with format/parse methods
 */
function timeFormatLocale(definition: TimeLocaleDefinition): TimeLocale;

/**
 * Get the default time locale
 * @returns Current default time locale
 */
function timeFormatDefaultLocale(): TimeLocale;

interface TimeLocaleDefinition {
  dateTime: string;          // Date/time format (e.g., "%x, %X")
  date: string;              // Date format (e.g., "%-m/%-d/%Y")
  time: string;              // Time format (e.g., "%-I:%M:%S %p")
  periods: [string, string]; // AM/PM indicators
  days: string[];            // Full weekday names
  shortDays: string[];       // Abbreviated weekday names
  months: string[];          // Full month names
  shortMonths: string[];     // Abbreviated month names
}

interface TimeLocale {
  format(specifier: string): (date: Date) => string;
  parse(specifier: string): (dateString: string) => Date | null;
  utcFormat(specifier: string): (date: Date) => string;
  utcParse(specifier: string): (dateString: string) => Date | null;
}

import { timeFormatLocale } from "d3";

// Spanish locale
const esLocale = timeFormatLocale({
  dateTime: "%A, %e de %B de %Y, %X",
  date: "%-m/%-d/%Y",
  time: "%-I:%M:%S %p",
  periods: ["AM", "PM"],
  days: ["domingo", "lunes", "martes", "miércoles", "jueves", "viernes", "sábado"],
  shortDays: ["dom", "lun", "mar", "mié", "jue", "vie", "sáb"],
  months: ["enero", "febrero", "marzo", "abril", "mayo", "junio", 
           "julio", "agosto", "septiembre", "octubre", "noviembre", "diciembre"],
  shortMonths: ["ene", "feb", "mar", "abr", "may", "jun",
                "jul", "ago", "sep", "oct", "nov", "dic"]
});

const spanishFormat = esLocale.format("%B %d, %Y");
spanishFormat(new Date(2023, 0, 15)); // "enero 15, 2023"

/**
 * Format date as ISO 8601 string (YYYY-MM-DDTHH:mm:ss.sssZ)
 * @param date - Date to format
 * @returns ISO 8601 formatted string
 */
function isoFormat(date: Date): string;

/**
 * Parse ISO 8601 date string
 * @param dateString - ISO 8601 formatted string
 * @returns Date object or null if invalid
 */
function isoParse(dateString: string): Date | null;