or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

calendar-systems.mddate-conversion.mddate-formatting.mddate-queries.mddate-time-objects.mdindex.mdstring-parsing.md
tile.json

tessl/npm-internationalized--date

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@internationalized/date@3.9.x

To install, run

npx @tessl/cli install tessl/npm-internationalized--date@3.9.0

index.mddocs/

Internationalized Date

The @internationalized/date library provides comprehensive, locale-aware date and time manipulation utilities with support for 13 international calendar systems. It offers immutable typed objects for dates, times, and date-time combinations with timezone support, designed for maximum reusability across internationalized applications requiring robust date handling.

Package Information

  • Package Name: @internationalized/date
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @internationalized/date

Core Imports

import { 
  CalendarDate, 
  CalendarDateTime, 
  Time, 
  ZonedDateTime,
  DateFormatter,
  createCalendar,
  parseDate,
  parseDateTime,
  parseZonedDateTime,
  now,
  today,
  startOfMonth,
  isWeekend
} from "@internationalized/date";

For CommonJS:

const { 
  CalendarDate, 
  CalendarDateTime, 
  Time, 
  ZonedDateTime,
  DateFormatter,
  createCalendar,
  parseDate,
  parseDateTime,
  parseZonedDateTime,
  now,
  today,
  startOfMonth,
  isWeekend
} = require("@internationalized/date");

Basic Usage

import { 
  CalendarDate, 
  ZonedDateTime, 
  now, 
  parseDate,
  parseDateTime,
  createCalendar,
  GregorianCalendar,
  startOfMonth,
  isWeekend
} from "@internationalized/date";

// Create dates in different calendar systems
const date = new CalendarDate(2024, 3, 15);
const persianDate = new CalendarDate(createCalendar('persian'), 1403, 1, 26);

// Work with timezone-aware dates
const zonedNow = now('America/New_York');
const zonedDate = new ZonedDateTime(2024, 3, 15, 'UTC', 0, 14, 30);

// Parse ISO strings
const parsedDate = parseDate('2024-03-15');
const parsedDateTime = parseDateTime('2024-03-15T14:30:00');

// Date arithmetic and manipulation
const nextWeek = date.add({ weeks: 1 });
const startOfMonth = startOfMonth(date);
const isWeekendDay = isWeekend(date, 'en-US');

Architecture

The @internationalized/date library is built around several key components:

  • Date/Time Objects: Four immutable classes (CalendarDate, CalendarDateTime, Time, ZonedDateTime) representing different temporal concepts
  • Calendar Systems: 13 international calendar implementations with consistent APIs
  • Conversion System: Functions for transforming between date types, calendar systems, and timezones
  • Query Functions: Utilities for comparing dates, getting date ranges, and locale-aware operations
  • Parsing System: ISO 8601 string parsing with support for dates, times, durations, and zoned datetimes
  • Formatting: Internationalized date formatting with browser compatibility fixes

Capabilities

Date and Time Objects

Core immutable date and time classes for representing temporal values in different calendar systems, with or without timezone information.

class CalendarDate {
  constructor(year: number, month: number, day: number);
  constructor(era: string, year: number, month: number, day: number);
  constructor(calendar: Calendar, year: number, month: number, day: number);
  constructor(calendar: Calendar, era: string, year: number, month: number, day: number);
  
  readonly calendar: Calendar;
  readonly era: string;
  readonly year: number;
  readonly month: number;
  readonly day: number;
}

class ZonedDateTime {
  constructor(year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
  constructor(era: string, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
  constructor(calendar: Calendar, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
  constructor(calendar: Calendar, era: string, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
  
  readonly calendar: Calendar;
  readonly era: string;
  readonly year: number;
  readonly month: number;
  readonly day: number;
  readonly hour: number;
  readonly minute: number;
  readonly second: number;
  readonly millisecond: number;
  readonly timeZone: string;
  readonly offset: number;
}

Date and Time Objects

Calendar Systems

Support for 13 international calendar systems including Gregorian, Buddhist, Islamic, Hebrew, Persian, and others with factory creation.

function createCalendar(identifier: CalendarIdentifier): Calendar;

type CalendarIdentifier = 'gregory' | 'buddhist' | 'chinese' | 'coptic' | 'dangi' | 
  'ethioaa' | 'ethiopic' | 'hebrew' | 'indian' | 'islamic' | 'islamic-umalqura' | 
  'islamic-tbla' | 'islamic-civil' | 'islamic-rgsa' | 'iso8601' | 'japanese' | 'persian' | 'roc';

Calendar Systems

Date Conversion and Transformation

Functions for converting between date types, calendar systems, and timezones with proper handling of ambiguous time situations.

function toCalendar<T extends AnyCalendarDate>(date: T, calendar: Calendar): T;
function toZoned(date: CalendarDate | CalendarDateTime | ZonedDateTime, timeZone: string, disambiguation?: Disambiguation): ZonedDateTime;
function fromDate(date: Date, timeZone: string): ZonedDateTime;
function fromAbsolute(ms: number, timeZone: string): ZonedDateTime;

type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject';

Date Conversion

Date Queries and Comparisons

Comprehensive set of functions for comparing dates, getting date ranges, and performing locale-aware date operations.

function isSameDay(a: DateValue, b: DateValue): boolean;
function isWeekend(date: DateValue, locale: string): boolean;
function now(timeZone: string): ZonedDateTime;
function today(timeZone: string): CalendarDate;
function startOfMonth<T extends DateValue>(date: T): T;
function endOfWeek(date: DateValue, locale: string, firstDayOfWeek?: DayOfWeek): DateValue;

Date Queries

String Parsing

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

function parseDate(value: string): CalendarDate;
function parseDateTime(value: string): CalendarDateTime;
function parseZonedDateTime(value: string, disambiguation?: Disambiguation): ZonedDateTime;
function parseDuration(value: string): Required<DateTimeDuration>;

String Parsing

Date Formatting

Internationalized date formatting with cross-browser compatibility and comprehensive format options.

class DateFormatter {
  constructor(locale: string, options?: Intl.DateTimeFormatOptions);
  format(date: Date): string;
  formatToParts(date: Date): Intl.DateTimeFormatPart[];
  formatRange(start: Date, end: Date): string;
}

Date Formatting

Types

interface AnyCalendarDate {
  readonly calendar: Calendar;
  readonly era: string;
  readonly year: number;
  readonly month: number;
  readonly day: number;
  copy(): this;
}

interface AnyTime {
  readonly hour: number;
  readonly minute: number;
  readonly second: number;
  readonly millisecond: number;
  copy(): this;
}

interface AnyDateTime extends AnyCalendarDate, AnyTime {}

interface DateDuration {
  years?: number;
  months?: number;
  weeks?: number;
  days?: number;
}

interface TimeDuration {
  hours?: number;
  minutes?: number;
  seconds?: number;
  milliseconds?: number;
}

interface DateTimeDuration extends DateDuration, TimeDuration {}

interface Calendar {
  identifier: CalendarIdentifier;
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}