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

Functional Programming

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

Complete functional programming interface providing curried versions of all date-fns-tz functions with reversed parameter order for optimal function composition and point-free programming style.

Overview

The FP module provides curried versions of all main functions where:

Parameters are in reverse order compared to regular functions
Functions are automatically curried for partial application
Designed for composition with function pipelines
Maintains full type safety with TypeScript

Core Imports

// Import all FP functions
import * as fp from "date-fns-tz/fp";

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

// Import individual functions
import formatInTimeZone from "date-fns-tz/fp/formatInTimeZone";
import toZonedTime from "date-fns-tz/fp/toZonedTime";

Currying Interface Types

// Base curried function types
type CurriedFn1<A, R> = (a: A) => R;
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;

Capabilities

Formatting Functions

format

Curried version of the format function with reversed parameter order.

/**
 * Curried format function: formatStr -> date -> result
 * @param formatStr - Format string with timezone tokens
 * @returns Curried function that takes a date and returns formatted string
 */
const format: CurriedFn2<string, Date | string | number, string>;

Usage Examples:

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

// Create specialized formatters
const formatTime = format('HH:mm:ss');
const formatDateISO = format('yyyy-MM-dd');

const date = new Date('2024-01-15T10:30:00Z');
console.log(formatTime(date)); // "10:30:00"
console.log(formatDateISO(date)); // "2024-01-15"

// Use in array operations
const dates = [
  new Date('2024-01-15T10:30:00Z'),
  new Date('2024-01-16T14:45:00Z'),
  new Date('2024-01-17T08:15:00Z'),
];

const formattedDates = dates.map(formatDateISO);
console.log(formattedDates); // ["2024-01-15", "2024-01-16", "2024-01-17"]

formatWithOptions

Curried format function with options support.

/**
 * Curried format with options: options -> formatStr -> date -> result
 * @param options - Formatting options including timezone
 * @returns Curried function chain
 */
const formatWithOptions: CurriedFn3<
  FormatOptionsWithTZ,
  string,
  Date | string | number,
  string
>;

Usage Examples:

import { formatWithOptions } from "date-fns-tz/fp";

// Create timezone-specific formatter
const formatInNY = formatWithOptions({ timeZone: 'America/New_York' });
const formatNYTime = formatInNY('yyyy-MM-dd HH:mm:ss zzz');

const date = new Date('2024-01-15T10:30:00Z');
console.log(formatNYTime(date)); // "2024-01-15 05:30:00 EST"

// Compose with different options
const formatters = [
  formatWithOptions({ timeZone: 'America/New_York' })('HH:mm z'),
  formatWithOptions({ timeZone: 'Europe/London' })('HH:mm z'),
  formatWithOptions({ timeZone: 'Asia/Tokyo' })('HH:mm z'),
];

const times = formatters.map(formatter => formatter(date));
console.log(times); // ["05:30 EST", "10:30 GMT", "19:30 JST"]

formatInTimeZone

Curried formatInTimeZone function.

/**
 * Curried formatInTimeZone: formatStr -> timeZone -> date -> result
 * @param formatStr - Format string
 * @returns Curried function chain
 */
const formatInTimeZone: CurriedFn3<
  string,
  string,
  Date | string | number,
  string
>;

Usage Examples:

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

// Create format-specific function
const formatDateTime = formatInTimeZone('yyyy-MM-dd HH:mm:ss zzz');

// Create timezone-specific function
const formatInTokyo = formatDateTime('Asia/Tokyo');
const formatInNY = formatDateTime('America/New_York');

const date = new Date('2024-01-15T10:30:00Z');
console.log(formatInTokyo(date)); // "2024-01-15 19:30:00 JST"
console.log(formatInNY(date)); // "2024-01-15 05:30:00 EST"

// Pipeline usage
const processDate = (date: Date) => [
  formatInTokyo,
  formatInNY,
  formatDateTime('Europe/London'),
].map(fn => fn(date));

console.log(processDate(date));

formatInTimeZoneWithOptions

Curried formatInTimeZone with options support.

/**
 * Curried formatInTimeZone with options: options -> formatStr -> timeZone -> date -> result
 * @param options - Formatting options
 * @returns Curried function chain
 */
const formatInTimeZoneWithOptions: CurriedFn4<
  FormatOptionsWithTZ,
  string,
  string,
  Date | string | number,
  string
>;

Timezone Conversion Functions

toZonedTime

Curried toZonedTime function.

/**
 * Curried toZonedTime: timeZone -> date -> result
 * @param timeZone - IANA time zone identifier or offset string
 * @returns Function that converts dates to zoned time
 */
const toZonedTime: CurriedFn2<string, Date | string | number, Date>;

Usage Examples:

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

// Create timezone converters
const toNYTime = toZonedTime('America/New_York');
const toTokyoTime = toZonedTime('Asia/Tokyo');
const toUTCTime = toZonedTime('UTC');

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

console.log(toNYTime(utcDate).getHours()); // 5
console.log(toTokyoTime(utcDate).getHours()); // 19
console.log(toUTCTime(utcDate).getHours()); // 10

// Process multiple dates
const dates = [
  new Date('2024-01-15T10:30:00Z'),
  new Date('2024-01-15T14:30:00Z'),
  new Date('2024-01-15T18:30:00Z'),
];

const nyTimes = dates.map(toNYTime);
nyTimes.forEach((date, i) => {
  console.log(`Date ${i + 1} in NY: ${date.getHours()}:${date.getMinutes()}`);
});

toZonedTimeWithOptions

Curried toZonedTime with options support.

/**
 * Curried toZonedTime with options: options -> timeZone -> date -> result
 * @param options - Parsing options
 * @returns Curried function chain
 */
const toZonedTimeWithOptions: CurriedFn3<
  ToDateOptionsWithTZ,
  string,
  Date | string | number,
  Date
>;

fromZonedTime

Curried fromZonedTime function.

/**
 * Curried fromZonedTime: timeZone -> date -> result
 * @param timeZone - IANA time zone identifier or offset string
 * @returns Function that converts zoned time to UTC
 */
const fromZonedTime: CurriedFn2<string, Date | string | number, Date>;

Usage Examples:

import { fromZonedTime } from "date-fns-tz/fp";

// Create UTC converters for different timezones
const fromNY = fromZonedTime('America/New_York');
const fromTokyo = fromZonedTime('Asia/Tokyo');
const fromLondon = fromZonedTime('Europe/London');

// Local time representations
const nyLocal = new Date(2024, 0, 15, 14, 30); // 2:30 PM in NY
const tokyoLocal = new Date(2024, 0, 15, 14, 30); // 2:30 PM in Tokyo

console.log(fromNY(nyLocal).toISOString());
console.log(fromTokyo(tokyoLocal).toISOString());

// Batch processing
const localTimes = [nyLocal, tokyoLocal];
const converters = [fromNY, fromTokyo];

const utcTimes = localTimes.map((time, i) => converters[i](time));
console.log(utcTimes.map(d => d.toISOString()));

fromZonedTimeWithOptions

Curried fromZonedTime with options support.

/**
 * Curried fromZonedTime with options: options -> timeZone -> date -> result
 * @param options - Parsing options
 * @returns Curried function chain
 */
const fromZonedTimeWithOptions: CurriedFn3<
  ToDateOptionsWithTZ,
  string,
  Date | string | number,
  Date
>;

getTimezoneOffset

Curried getTimezoneOffset function.

/**
 * Curried getTimezoneOffset: timeZone -> date -> result
 * @param timeZone - IANA time zone identifier or offset string
 * @returns Function that gets timezone offset for dates
 */
const getTimezoneOffset: CurriedFn2<string, Date | number | undefined, number>;

Usage Examples:

import { getTimezoneOffset } from "date-fns-tz/fp";

// Create offset calculators
const getNYOffset = getTimezoneOffset('America/New_York');
const getTokyoOffset = getTimezoneOffset('Asia/Tokyo');
const getLondonOffset = getTimezoneOffset('Europe/London');

const winterDate = new Date('2024-01-15');
const summerDate = new Date('2024-07-15');

// Check seasonal offsets
const timezones = [getNYOffset, getLondonOffset];
const seasons = [winterDate, summerDate];

seasons.forEach((date, seasonIdx) => {
  console.log(seasonIdx ? 'Summer:' : 'Winter:');
  timezones.forEach((getOffset, tzIdx) => {
    const offset = getOffset(date);
    console.log(`  TZ ${tzIdx}: ${offset / 1000 / 60 / 60} hours`);
  });
});

Date Parsing Functions

toDate

Curried toDate function.

/**
 * Curried toDate: date -> result
 * @param argument - Value to convert to Date
 * @returns Converted Date instance
 */
const toDate: CurriedFn1<Date | string | number, Date>;

Usage Examples:

import { toDate } from "date-fns-tz/fp";

// Use in array operations
const dateInputs = [
  '2024-01-15T10:30:00Z',
  1705315800000,
  '2024-01-16T14:45:00+05:30',
];

const parsedDates = dateInputs.map(toDate);
parsedDates.forEach(date => {
  console.log(date.toISOString());
});

// Compose with other operations
const processDateString = (dateStr: string) => {
  const date = toDate(dateStr);
  return date.toISOString();
};

console.log(processDateString('2024-01-15T10:30:00Z'));

toDateWithOptions

Curried toDate with options support.

/**
 * Curried toDate with options: options -> date -> result
 * @param options - Parsing options including timezone
 * @returns Function that converts with specified options
 */
const toDateWithOptions: CurriedFn2<
  ToDateOptionsWithTZ,
  Date | string | number,
  Date
>;

Usage Examples:

import { toDateWithOptions } from "date-fns-tz/fp";

// Create timezone-specific parsers
const parseInNY = toDateWithOptions({ timeZone: 'America/New_York' });
const parseInTokyo = toDateWithOptions({ timeZone: 'Asia/Tokyo' });

const localTimeString = '2024-01-15T14:30:00';

const nyTime = parseInNY(localTimeString);
const tokyoTime = parseInTokyo(localTimeString);

console.log('NY interpretation:', nyTime.toISOString());
console.log('Tokyo interpretation:', tokyoTime.toISOString());

Function Composition Patterns

Pipeline Operations

import { formatInTimeZone, toZonedTime } from "date-fns-tz/fp";
import { pipe } from "ramda"; // or similar utility

// Create a processing pipeline
const processUTCDate = pipe(
  toZonedTime('America/New_York'),
  (date: Date) => formatInTimeZone('yyyy-MM-dd HH:mm:ss zzz')('America/New_York')(date)
);

const utcDate = new Date('2024-01-15T10:30:00Z');
console.log(processUTCDate(utcDate)); // "2024-01-15 05:30:00 EST"

Point-Free Style Programming

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

// Point-free date processors
const formatAsISO = formatInTimeZone('yyyy-MM-dd');
const convertToNY = toZonedTime('America/New_York');
const getNYOffset = getTimezoneOffset('America/New_York');

// Array processing without explicit parameters
const dates = [
  new Date('2024-01-15T10:30:00Z'),
  new Date('2024-06-15T10:30:00Z'),
];

const nyDates = dates.map(convertToNY);
const isoStrings = dates.map(formatAsISO('UTC'));
const offsets = dates.map(getNYOffset);

console.log('NY dates:', nyDates);
console.log('ISO strings:', isoStrings);
console.log('Offsets (hours):', offsets.map(ms => ms / 1000 / 60 / 60));

Multi-Timezone Processing

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

// Create processors for multiple timezones
const timezones = ['America/New_York', 'Europe/London', 'Asia/Tokyo'];
const format24h = formatInTimeZone('HH:mm:ss zzz');

// Create specialized formatters
const formatters = timezones.map(tz => format24h(tz));

// Process a single date across timezones
const processAcrossTimezones = (date: Date) => 
  formatters.map(formatter => formatter(date));

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

console.log('World times:', worldTimes);
// ["05:30:00 EST", "10:30:00 GMT", "19:30:00 JST"]

Conditional Processing

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

// Create conditional processors based on user preference
interface UserPrefs {
  timezone: string;
  format24h: boolean;
}

function createUserFormatter(prefs: UserPrefs) {
  const formatStr = prefs.format24h ? 'HH:mm:ss' : 'h:mm:ss a';
  return formatInTimeZone(formatStr)(prefs.timezone);
}

const users = [
  { timezone: 'America/New_York', format24h: false },
  { timezone: 'Europe/Berlin', format24h: true },
  { timezone: 'Asia/Tokyo', format24h: true },
];

const formatters = users.map(createUserFormatter);
const date = new Date('2024-01-15T10:30:00Z');

const userFormattedTimes = formatters.map(formatter => formatter(date));
console.log('User formatted times:', userFormattedTimes);

Advanced FP Patterns

Partial Application with Configuration

import { formatInTimeZoneWithOptions } from "date-fns-tz/fp";

// Create a configurable formatter factory
const createFormatter = (locale: any, use24h: boolean) => 
  formatInTimeZoneWithOptions({ locale, useAdditionalWeekYearTokens: true });

// Pre-configure with specific options
const formatWithLocale = createFormatter(undefined, true);
const formatDateTime = formatWithLocale('yyyy-MM-dd HH:mm:ss zzz');

// Create timezone-specific formatters
const formatInMultipleZones = (timezones: string[]) =>
  timezones.map(tz => formatDateTime(tz));

const worldClockFormatter = formatInMultipleZones([
  'America/New_York',
  'Europe/London', 
  'Asia/Tokyo'
]);

const date = new Date('2024-01-15T10:30:00Z');
const worldTimes = worldClockFormatter.map(formatter => formatter(date));
console.log('World clock:', worldTimes);

Error Handling in FP Style

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

// Safe wrapper for FP functions
const safeFormat = (formatStr: string) => (timezone: string) => (date: any) => {
  try {
    const parsedDate = toDate(date);
    if (isNaN(parsedDate.getTime())) {
      return 'Invalid Date';
    }
    return formatInTimeZone(formatStr)(timezone)(parsedDate);
  } catch (error) {
    return `Error: ${error.message}`;
  }
};

const safeFormatter = safeFormat('yyyy-MM-dd HH:mm:ss');
const formatInNY = safeFormatter('America/New_York');

const testInputs = [
  '2024-01-15T10:30:00Z',
  'invalid-date',
  1705315800000,
  null,
];

const results = testInputs.map(formatInNY);
console.log('Safe formatting results:', results);

docs

date-parsing.md

formatting.md

functional-programming.md

index.md

timezone-conversion.md

tile.json

tessl/npm-date-fns-tz