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

index.mddocs/

date-fns-tz

date-fns-tz provides comprehensive time zone support for date-fns v3+ using the native Intl API. It offers timezone-aware formatting, conversion functions, and a complete functional programming interface for handling dates across different time zones with proper DST handling.

Package Information

  • Package Name: date-fns-tz
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install date-fns-tz
  • Peer Dependency: date-fns@^3.0.0

Core Imports

import { 
  format, 
  formatInTimeZone, 
  toZonedTime, 
  fromZonedTime, 
  getTimezoneOffset,
  toDate 
} from "date-fns-tz";

For CommonJS:

const { 
  format, 
  formatInTimeZone, 
  toZonedTime, 
  fromZonedTime, 
  getTimezoneOffset,
  toDate 
} = require("date-fns-tz");

Individual imports:

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

Functional programming imports:

import { formatInTimeZone, toZonedTime } from "date-fns-tz/fp";

Basic Usage

import { formatInTimeZone, toZonedTime, fromZonedTime } from "date-fns-tz";

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

// Format a date in a specific timezone
const formatted = formatInTimeZone(date, 'America/New_York', 'yyyy-MM-dd HH:mm:ss zzz');
// Result: "2024-01-15 05:30:00 EST"

// Convert UTC date to represent local time in timezone
const nyTime = toZonedTime(date, 'America/New_York');
console.log(nyTime.getHours()); // 5 (represents 5 AM in NY)

// Convert local time in timezone back to UTC
const utcTime = fromZonedTime(nyTime, 'America/New_York');
console.log(utcTime.toISOString()); // "2024-01-15T10:30:00.000Z"

Architecture

date-fns-tz is built around several key components:

  • Core Functions: Six main functions handling formatting and timezone conversion
  • Timezone Support: Full IANA timezone database support via native Intl API
  • Format Tokens: Custom timezone format tokens (X, x, O, z) extending date-fns
  • FP Interface: Complete functional programming module with curried functions
  • Type Safety: Full TypeScript support with comprehensive type definitions
  • DST Handling: Proper daylight saving time transition support

Capabilities

Date Formatting

Timezone-aware date formatting with custom timezone tokens and locale support.

function format(
  date: Date | string | number, 
  formatStr: string, 
  options?: FormatOptionsWithTZ
): string;

function formatInTimeZone(
  date: Date | string | number,
  timeZone: string,
  formatStr: string,
  options?: FormatOptionsWithTZ
): string;

Formatting

Timezone Conversion

Convert dates between timezones and get timezone offset information.

function toZonedTime(
  date: Date | string | number,
  timeZone: string,
  options?: ToDateOptionsWithTZ
): Date;

function fromZonedTime(
  date: Date | string | number,
  timeZone: string,
  options?: ToDateOptionsWithTZ
): Date;

function getTimezoneOffset(timeZone: string, date?: Date | number): number;

Timezone Conversion

Date Parsing

Enhanced date parsing with timezone support for ISO strings and various date formats.

function toDate(
  argument: Date | string | number,
  options?: ToDateOptionsWithTZ
): Date;

Date Parsing

Functional Programming

Complete FP interface with curried functions and reversed parameter order for composition.

// Curried function types
type CurriedFn2<A, B, R> = (a: A) => (b: B) => R;
type CurriedFn3<A, B, C, R> = (a: A) => (b: B) => (c: C) => R;
type CurriedFn4<A, B, C, D, R> = (a: A) => (b: B) => (c: C) => (d: D) => R;

Functional Programming

Core Types

interface FormatOptionsWithTZ {
  locale?: FormatOptions['locale'] & Pick<Locale, 'code'>;
  timeZone?: string;
  originalDate?: Date | string | number;
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
  useAdditionalWeekYearTokens?: boolean;
  useAdditionalDayOfYearTokens?: boolean;
}

interface ToDateOptionsWithTZ {
  timeZone?: string;
  additionalDigits?: 0 | 1 | 2;
}

Timezone Support

  • IANA Timezone Names: Full support for identifiers like 'America/New_York', 'Europe/London'
  • Offset Strings: Support for ±HH:MM, ±HHMM, ±HH, Z formats
  • DST Handling: Automatic daylight saving time transitions
  • Intl Integration: Uses native Intl.DateTimeFormat for accurate timezone data

Format Tokens

In addition to all date-fns format tokens, date-fns-tz provides:

  • X: ISO 8601 timezone offset with Z for UTC (+05:30, Z)
  • x: ISO 8601 timezone offset without Z for UTC (+0530, +00)
  • O: GMT timezone offset (GMT+5:30, GMT)
  • z: Timezone name (EST, Pacific Standard Time)