tessl/npm-date-fns-tz

Time zone support for date-fns v3 with the Intl API

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Date Formatting

Name: tessl/npm-date-fns-tz
Author: tessl

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"