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-fns-tz

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

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