CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-internationalized--date

Internationalized calendar, date, and time manipulation utilities with support for 13 international calendar systems

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

string-parsing.mddocs/

String Parsing

ISO 8601 string parsing for dates, times, durations, and timezone-aware datetimes with comprehensive format support.

Capabilities

Date Parsing

Parse ISO 8601 date strings into CalendarDate objects.

/**
 * Parses an ISO 8601 date string, with no time components
 * @param value - ISO 8601 date string (e.g., "2024-03-15")
 * @returns CalendarDate object representing the parsed date
 * @throws Error if string format is invalid
 */
function parseDate(value: string): CalendarDate;

Usage Examples:

import { parseDate } from "@internationalized/date";

// Basic date parsing
const date1 = parseDate("2024-03-15"); // March 15, 2024
const date2 = parseDate("2024-12-31"); // December 31, 2024

// Extended year format (6 digits)
const ancientDate = parseDate("+001985-01-01"); // Year 1985
const futureDate = parseDate("+012024-06-15"); // Year 12024

// Negative years (BCE)
const bceDate = parseDate("-000100-07-20"); // 100 BCE

Time Parsing

Parse ISO 8601 time strings into Time objects.

/**
 * Parses an ISO 8601 time string
 * @param value - ISO 8601 time string (e.g., "14:30:00", "09:15:30.750")
 * @returns Time object representing the parsed time
 * @throws Error if string format is invalid
 */
function parseTime(value: string): Time;

Usage Examples:

import { parseTime } from "@internationalized/date";

// Basic time formats
const time1 = parseTime("14:30"); // 2:30 PM (seconds and ms default to 0)
const time2 = parseTime("14:30:00"); // 2:30:00 PM
const time3 = parseTime("14:30:45"); // 2:30:45 PM

// With milliseconds
const preciseTime = parseTime("14:30:45.750"); // 2:30:45.750 PM
const moreMs = parseTime("09:15:30.123456"); // 9:15:30.123 AM (truncated to ms)

// Edge cases
const midnight = parseTime("00:00:00"); // Midnight
const almostMidnight = parseTime("23:59:59.999"); // 11:59:59.999 PM

DateTime Parsing

Parse ISO 8601 datetime strings into CalendarDateTime objects.

/**
 * Parses an ISO 8601 datetime string
 * @param value - ISO 8601 datetime string (e.g., "2024-03-15T14:30:00")
 * @returns CalendarDateTime object representing the parsed datetime
 * @throws Error if string format is invalid
 */
function parseDateTime(value: string): CalendarDateTime;

Usage Examples:

import { parseDateTime } from "@internationalized/date";

// Basic datetime formats
const dt1 = parseDateTime("2024-03-15T14:30:00"); // March 15, 2024 at 2:30 PM
const dt2 = parseDateTime("2024-03-15T14:30"); // Seconds default to 0
const dt3 = parseDateTime("2024-03-15T14"); // Minutes and seconds default to 0

// With milliseconds
const preciseDateTime = parseDateTime("2024-03-15T14:30:45.750");

// Extended formats
const extendedYear = parseDateTime("+012024-12-31T23:59:59");
const bceDateTime = parseDateTime("-001000-06-15T12:00:00");

Absolute Time Parsing

Parse ISO 8601 absolute time strings with UTC offsets into ZonedDateTime objects.

/**
 * Parses an ISO 8601 absolute time with UTC offset
 * @param value - ISO 8601 string with UTC offset (e.g., "2024-03-15T14:30:00Z", "2024-03-15T14:30:00-05:00")
 * @param timeZone - IANA timezone identifier for the resulting ZonedDateTime
 * @returns ZonedDateTime representing the parsed absolute time
 * @throws Error if string format is invalid
 */
function parseAbsolute(value: string, timeZone: string): ZonedDateTime;

/**
 * Parses an ISO 8601 absolute time to local timezone
 * @param value - ISO 8601 string with UTC offset
 * @returns ZonedDateTime in user's local timezone
 * @throws Error if string format is invalid
 */
function parseAbsoluteToLocal(value: string): ZonedDateTime;

Usage Examples:

import { parseAbsolute, parseAbsoluteToLocal } from "@internationalized/date";

// UTC time (Z suffix)
const utcTime = parseAbsolute("2024-03-15T14:30:00Z", "America/New_York");

// With timezone offsets
const withOffset1 = parseAbsolute("2024-03-15T14:30:00-05:00", "UTC");
const withOffset2 = parseAbsolute("2024-03-15T14:30:00+09:00", "Asia/Tokyo");

// Different offset formats
const colonOffset = parseAbsolute("2024-03-15T14:30:00-05:00", "America/New_York");
const noColonOffset = parseAbsolute("2024-03-15T14:30:00-0500", "America/New_York");

// Parse to local timezone
const localTime = parseAbsoluteToLocal("2024-03-15T14:30:00Z");
const localWithOffset = parseAbsoluteToLocal("2024-03-15T14:30:00-05:00");

Zoned DateTime Parsing

Parse ISO 8601 strings with timezone identifiers into ZonedDateTime objects.

/**
 * Parses an ISO 8601 zoned datetime string
 * @param value - ISO 8601 string with timezone (e.g., "2024-03-15T14:30:00[America/New_York]")
 * @param disambiguation - How to handle ambiguous times during DST transitions
 * @returns ZonedDateTime representing the parsed zoned datetime
 * @throws Error if string format is invalid
 */
function parseZonedDateTime(value: string, disambiguation?: Disambiguation): ZonedDateTime;

Usage Examples:

import { parseZonedDateTime } from "@internationalized/date";

// Basic zoned datetime
const zonedDT = parseZonedDateTime("2024-03-15T14:30:00[America/New_York]");

// With UTC offset and timezone
const fullFormat = parseZonedDateTime("2024-03-15T14:30:00-05:00[America/New_York]");

// Different timezone formats
const utcZoned = parseZonedDateTime("2024-03-15T14:30:00Z[UTC]");
const europeZoned = parseZonedDateTime("2024-03-15T14:30:00+01:00[Europe/Paris]");

// Handle DST ambiguity
const ambiguousTime = "2024-11-03T01:30:00[America/New_York]"; // DST ends, 1:30 happens twice
const firstOccurrence = parseZonedDateTime(ambiguousTime, 'earlier');
const secondOccurrence = parseZonedDateTime(ambiguousTime, 'later');

// Invalid time during spring forward
const invalidTime = "2024-03-10T02:30:00[America/New_York]"; // 2:30 AM doesn't exist
const resolvedTime = parseZonedDateTime(invalidTime, 'compatible'); // Resolved to 3:30 AM

Duration Parsing

Parse ISO 8601 duration strings into duration objects.

/**
 * Parses an ISO 8601 duration string
 * @param value - ISO 8601 duration string (e.g., "P1Y2M3DT4H5M6S")
 * @returns Required<DateTimeDuration> with all duration fields present
 * @throws Error if string format is invalid
 */
function parseDuration(value: string): Required<DateTimeDuration>;

Usage Examples:

import { parseDuration } from "@internationalized/date";

// Basic duration formats
const duration1 = parseDuration("P1Y"); // 1 year
const duration2 = parseDuration("P2M"); // 2 months  
const duration3 = parseDuration("P3D"); // 3 days
const duration4 = parseDuration("PT4H"); // 4 hours
const duration5 = parseDuration("PT5M"); // 5 minutes
const duration6 = parseDuration("PT6S"); // 6 seconds

// Combined durations
const combined = parseDuration("P1Y2M3DT4H5M6S"); // 1y 2m 3d 4h 5m 6s
const dateOnly = parseDuration("P1Y6M15D"); // 1 year 6 months 15 days
const timeOnly = parseDuration("PT8H30M45S"); // 8 hours 30 minutes 45 seconds

// Weeks
const weeks = parseDuration("P2W"); // 2 weeks
const weeksAndDays = parseDuration("P2W3D"); // 2 weeks 3 days

// Fractional values
const fractionalHours = parseDuration("PT2.5H"); // 2.5 hours
const fractionalMinutes = parseDuration("PT30.75M"); // 30.75 minutes
const fractionalSeconds = parseDuration("PT45.123S"); // 45.123 seconds

// Negative durations
const negative = parseDuration("-P1Y2M3D"); // Negative 1y 2m 3d

// Use with date arithmetic
const date = parseDate("2024-03-15");
const duration = parseDuration("P1M2D");
const futureDate = date.add(duration); // April 17, 2024

Advanced Parsing Scenarios

Handle complex parsing scenarios and error cases.

Parsing with Error Handling:

import { 
  parseDate, 
  parseDateTime, 
  parseZonedDateTime 
} from "@internationalized/date";

function safeParse(dateString: string) {
  try {
    // Try different parsing strategies
    if (dateString.includes('T')) {
      if (dateString.includes('[')) {
        return parseZonedDateTime(dateString);
      } else {
        return parseDateTime(dateString);
      }
    } else {
      return parseDate(dateString);
    }
  } catch (error) {
    console.error('Failed to parse date string:', dateString, error);
    return null;
  }
}

// Usage
const parsed1 = safeParse("2024-03-15"); // CalendarDate
const parsed2 = safeParse("2024-03-15T14:30:00"); // CalendarDateTime  
const parsed3 = safeParse("2024-03-15T14:30:00[UTC]"); // ZonedDateTime
const parsed4 = safeParse("invalid"); // null

Complex Duration Parsing:

import { parseDuration, CalendarDateTime } from "@internationalized/date";

// Parse and apply different duration types
const baseDateTime = new CalendarDateTime(2024, 1, 1, 12, 0, 0);

const yearDuration = parseDuration("P1Y");
const monthDuration = parseDuration("P6M");
const weekDuration = parseDuration("P2W");
const dayDuration = parseDuration("P10D");
const timeDuration = parseDuration("PT12H30M");
const complexDuration = parseDuration("P1Y2M3DT4H5M6.789S");

// Apply durations
const afterYear = baseDateTime.add(yearDuration);
const afterMonth = baseDateTime.add(monthDuration);
const afterComplex = baseDateTime.add(complexDuration);

Types

/**
 * Disambiguation strategy for handling ambiguous times during DST transitions
 */
type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject';

/**
 * Represents an amount of time with both date and time components
 */
interface DateTimeDuration extends DateDuration, TimeDuration {}

/**
 * Represents an amount of time in calendar-specific units
 */
interface DateDuration {
  years?: number;
  months?: number;
  weeks?: number;
  days?: number;
}

/**
 * Represents an amount of time in time units
 */
interface TimeDuration {
  hours?: number;
  minutes?: number;
  seconds?: number;
  milliseconds?: number;
}

docs

calendar-systems.md

date-conversion.md

date-formatting.md

date-queries.md

date-time-objects.md

index.md

string-parsing.md

tile.json