ISO Date Utilities

/**
 * Format specifier for ISO 8601 datetime strings
 * Value: "%Y-%m-%dT%H:%M:%S.%LZ"
 */
const isoSpecifier: string;

import { isoSpecifier, utcFormat } from "d3-time-format";

// Use the ISO specifier with custom formatters
const customIsoFormat = utcFormat(isoSpecifier);
customIsoFormat(new Date()); // Same as isoFormat()

console.log(isoSpecifier); // "%Y-%m-%dT%H:%M:%S.%LZ"

/**
 * Formats a date as ISO 8601 UTC string
 * Uses native Date.toISOString() when available for optimal performance
 * @param date - Date object to format
 * @returns ISO 8601 formatted string (YYYY-MM-DDTHH:mm:ss.sssZ)
 */
function isoFormat(date: Date): string;

import { isoFormat } from "d3-time-format";

const date = new Date(2015, 5, 30, 12, 30, 45, 123);
isoFormat(date); // "2015-06-30T19:30:45.123Z" (assuming UTC-7 timezone)

// Always outputs in UTC regardless of local timezone
const utcDate = new Date(Date.UTC(2015, 5, 30, 12, 30, 45, 123));
isoFormat(utcDate); // "2015-06-30T12:30:45.123Z"

/**
 * Parses ISO 8601 formatted strings to Date objects
 * Uses native Date constructor when available for optimal performance
 * @param dateString - ISO 8601 formatted string
 * @returns Date object or null if parsing fails
 */
function isoParse(dateString: string): Date | null;

import { isoParse } from "d3-time-format";

// Standard ISO 8601 formats
isoParse("2015-06-30T19:30:45.123Z"); // Date object
isoParse("2015-06-30T19:30:45Z");     // Date object (no milliseconds)
isoParse("2015-06-30T19:30:45");      // Date object (local time interpretation)
isoParse("2015-06-30");               // Date object (midnight local time)

// Invalid formats return null
isoParse("invalid-date");             // null
isoParse("2015-13-30");               // null (invalid month)
isoParse("");                         // null

// ISO 8601 format pattern
"YYYY-MM-DDTHH:mm:ss.sssZ"

// Components:
YYYY  // 4-digit year
MM    // 2-digit month (01-12)
DD    // 2-digit day (01-31)  
T     // Literal 'T' separator
HH    // 2-digit hour (00-23)
mm    // 2-digit minute (00-59)
ss    // 2-digit second (00-59)
sss   // 3-digit millisecond (000-999)
Z     // UTC timezone indicator

// Internal implementation strategy
const isoFormat = Date.prototype.toISOString
  ? (date) => date.toISOString()  // Native implementation
  : utcFormat("%Y-%m-%dT%H:%M:%S.%LZ");  // Fallback

// Internal implementation strategy  
const isoParse = (new Date("2000-01-01T00:00:00.000Z")).getTime()
  ? (string) => {  // Native implementation
      const date = new Date(string);
      return isNaN(date) ? null : date;
    }
  : utcParse("%Y-%m-%dT%H:%M:%S.%LZ");  // Fallback

import { utcParse } from "d3-time-format";

/**
 * Strict ISO 8601 parser that requires exact format compliance
 * @param dateString - Must exactly match ISO format
 * @returns Date object or null for non-compliant input
 */
const strictIsoParse = utcParse("%Y-%m-%dT%H:%M:%S.%LZ");

// Strict parsing examples
strictIsoParse("2015-06-30T19:30:45.123Z"); // ✓ Valid
strictIsoParse("2015-06-30T19:30:45Z");     // ✗ null (missing milliseconds)
strictIsoParse("2015-06-30 19:30:45");      // ✗ null (space instead of T)

import { isoFormat, isoParse } from "d3-time-format";

// Serialize dates for APIs
const data = {
  timestamp: isoFormat(new Date()),
  created_at: isoFormat(someDate)
};

// Parse dates from API responses
const parsed = {
  timestamp: isoParse(response.timestamp),
  created_at: isoParse(response.created_at)
};

import { isoFormat } from "d3-time-format";

function log(message) {
  console.log(`[${isoFormat(new Date())}] ${message}`);
}

log("Application started"); 
// [2015-06-30T19:30:45.123Z] Application started

import { isoParse } from "d3-time-format";

const timeSeriesData = csvData.map(row => ({
  timestamp: isoParse(row.timestamp),
  value: +row.value
})).filter(d => d.timestamp !== null); // Remove invalid dates