or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

date-parsing.mdformatting.mdfunctional-programming.mdindex.mdtimezone-conversion.md
tile.json

formatting.mddocs/

Date Formatting

Timezone-aware date formatting functions that extend date-fns with custom timezone formatting tokens and timezone conversion capabilities.

Capabilities

format Function

Format a date with timezone-aware formatting tokens, extending date-fns format with timezone-specific tokens.

/**
 * Format a date with timezone-aware formatting tokens (X, x, O, z)
 * @param date - The date to format
 * @param formatStr - Format string with Unicode tokens and timezone tokens
 * @param options - Formatting options including timezone
 * @returns Formatted date string
 */
function format(
  date: Date | string | number,
  formatStr: string,
  options?: FormatOptionsWithTZ
): string;

Usage Examples:

import { format } from "date-fns-tz";

const date = new Date('2024-01-15T10:30:00Z');

// Basic formatting with timezone tokens
format(date, "yyyy-MM-dd HH:mm:ss X", { timeZone: 'America/New_York' });
// Result: "2024-01-15 05:30:00 -05:00"

// Timezone name formatting
format(date, "yyyy-MM-dd HH:mm:ss z", { timeZone: 'Europe/London' });
// Result: "2024-01-15 10:30:00 GMT"

// Multiple timezone tokens
format(date, "HH:mm O (z)", { timeZone: 'Asia/Tokyo' });
// Result: "19:30 GMT+9:00 (JST)"

formatInTimeZone Function

Format a date in a specific timezone, converting the date to the target timezone before formatting.

/**
 * Format a date in a specific timezone
 * @param date - The date representing local time / real UTC time
 * @param timeZone - IANA time zone identifier or offset string
 * @param formatStr - Format string
 * @param options - Additional formatting options
 * @returns Formatted date string in the specified timezone
 */
function formatInTimeZone(
  date: Date | string | number,
  timeZone: string,
  formatStr: string,
  options?: FormatOptionsWithTZ
): string;

Usage Examples:

import { formatInTimeZone } from "date-fns-tz";

const date = new Date('2024-01-15T10:30:00Z');

// Format in different timezones
formatInTimeZone(date, 'America/New_York', 'yyyy-MM-dd HH:mm:ss zzz');
// Result: "2024-01-15 05:30:00 EST"

formatInTimeZone(date, 'Asia/Tokyo', 'PP pp');
// Result: "Jan 15, 2024 at 7:30:00 PM"

formatInTimeZone(date, 'Europe/Paris', "EEEE, MMMM do, yyyy 'at' HH:mm O");
// Result: "Monday, January 15th, 2024 at 11:30 GMT+1:00"

// Using offset strings
formatInTimeZone(date, '+05:30', 'HH:mm:ss');
// Result: "16:00:00"

Timezone Format Tokens

These special tokens are available in addition to all standard date-fns format tokens:

ISO 8601 Timezone Offset (X)

// X token: ISO 8601 timezone offset with Z for UTC
// Examples: +05:30, -08:00, Z

Examples:

format(new Date('2024-01-15T10:30:00Z'), 'HH:mm X', { timeZone: 'UTC' });
// Result: "10:30 Z"

format(new Date('2024-01-15T10:30:00Z'), 'HH:mm X', { timeZone: 'Asia/Kolkata' });
// Result: "16:00 +05:30"

ISO 8601 Timezone Offset Without Z (x)

// x token: ISO 8601 timezone offset without Z for UTC
// Examples: +0530, -0800, +0000

Examples:

format(new Date('2024-01-15T10:30:00Z'), 'HH:mm x', { timeZone: 'UTC' });
// Result: "10:30 +0000"

format(new Date('2024-01-15T10:30:00Z'), 'HH:mm x', { timeZone: 'America/Los_Angeles' });
// Result: "02:30 -0800"

GMT Timezone Offset (O)

// O token: GMT timezone offset
// Examples: GMT+5:30, GMT-8:00, GMT

Examples:

format(new Date('2024-01-15T10:30:00Z'), 'HH:mm O', { timeZone: 'Australia/Sydney' });
// Result: "21:30 GMT+11:00"

format(new Date('2024-01-15T10:30:00Z'), 'HH:mm O', { timeZone: 'UTC' });
// Result: "10:30 GMT"

Timezone Name (z)

// z token: Timezone name (short or long form based on context)
// Examples: EST, PST, Eastern Standard Time

Examples:

format(new Date('2024-01-15T10:30:00Z'), 'HH:mm z', { timeZone: 'America/New_York' });
// Result: "05:30 EST"

format(new Date('2024-07-15T10:30:00Z'), 'HH:mm z', { timeZone: 'America/New_York' });
// Result: "06:30 EDT" (daylight saving time)

Options Interface

interface FormatOptionsWithTZ {
  /** Locale for formatting */
  locale?: FormatOptions['locale'] & Pick<Locale, 'code'>;
  /** IANA time zone identifier or offset string */
  timeZone?: string;
  /** Original unmodified date for better DST handling */
  originalDate?: Date | string | number;
  /** First day of the week (0 = Sunday, 1 = Monday, etc.) */
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  /** First week contains date (1-7) */
  firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
  /** Allow additional week year tokens */
  useAdditionalWeekYearTokens?: boolean;
  /** Allow additional day of year tokens */
  useAdditionalDayOfYearTokens?: boolean;
}

Locale Support

import { format } from "date-fns-tz";
import { es, de, ja } from "date-fns/locale";

const date = new Date('2024-01-15T10:30:00Z');

// Spanish locale
format(date, "EEEE, MMMM do, yyyy", { 
  timeZone: 'Europe/Madrid',
  locale: es 
});
// Result: "lunes, enero 15o, 2024"

// German locale with timezone
format(date, "PPPP 'um' HH:mm O", { 
  timeZone: 'Europe/Berlin',
  locale: de 
});
// Result: "Montag, 15. Januar 2024 um 11:30 GMT+1:00"

DST Handling

The formatting functions properly handle Daylight Saving Time transitions:

import { formatInTimeZone } from "date-fns-tz";

// Before DST (Standard Time)
const winterDate = new Date('2024-01-15T10:30:00Z');
formatInTimeZone(winterDate, 'America/New_York', 'HH:mm z');
// Result: "05:30 EST"

// After DST (Daylight Time)
const summerDate = new Date('2024-07-15T10:30:00Z');
formatInTimeZone(summerDate, 'America/New_York', 'HH:mm z');
// Result: "06:30 EDT"

Error Handling

// Invalid timezone throws RangeError
try {
  format(new Date(), 'HH:mm', { timeZone: 'Invalid/Timezone' });
} catch (error) {
  console.log(error instanceof RangeError); // true
}

// Invalid date returns "Invalid Date"
format(new Date('invalid'), 'yyyy-MM-dd');
// Result: "Invalid Date"