index.md

title	API Reference

Welcome to the comprehensive API reference for date-and-time v4.x. This section provides detailed documentation for all available functions, types, and options.

Core Functions

Formatting and Parsing

Function	Description
format()	Convert Date objects to formatted strings
parse()	Parse date strings into Date objects
compile()	Precompile format patterns for performance
preparse()	Parse and return intermediate parsing results
isValid()	Validate date string formats
transform()	Transform date strings between formats

Date Arithmetic

Function	Description
addYears()	Add/subtract years from dates
addMonths()	Add/subtract months from dates
addDays()	Add/subtract days from dates
addHours()	Add/subtract hours from dates
addMinutes()	Add/subtract minutes from dates
addSeconds()	Add/subtract seconds from dates
addMilliseconds()	Add/subtract milliseconds from dates
subtract()	Calculate time differences with Duration objects

Utility Functions

Function	Description
isLeapYear()	Check if a year is a leap year
isSameDay()	Check if two dates are on the same day
getDaysInMonth()	Get the number of days in a month
getISOWeekYear()	Get the ISO week year for a date
getISOWeek()	Get the ISO week number for a date

Quick Examples

Basic Usage

import { format, parse, isValid } from 'date-and-time'

// Formatting
const date = new Date()
format(date, 'YYYY-MM-DD HH:mm:ss');
// => 2025-08-23 14:30:45

// Parsing
const parsed = parse('2025-08-23 14:30:45', 'YYYY-MM-DD HH:mm:ss');
// => Date object

// Validation
isValid('2025-02-29', 'YYYY-MM-DD'); // => false (not a leap year)

With Options

import { format } from 'date-and-time';
import ja from 'date-and-time/locales/ja';

format(new Date(), 'YYYY年M月D日(ddd) HH:mm', {
  locale: ja,
  timeZone: 'Asia/Tokyo'
});
// => 2025年8月23日(土) 23:30

Supported Locales

date-and-time supports 40+ locales. Import only the ones you need:

// Examples
import ar from 'date-and-time/locales/ar';          // Arabic
import ja from 'date-and-time/locales/ja';          // Japanese
import es from 'date-and-time/locales/es';          // Spanish
import fr from 'date-and-time/locales/fr';          // French
import de from 'date-and-time/locales/de';          // German
import ru from 'date-and-time/locales/ru';          // Russian
import zhHans from 'date-and-time/locales/zh-Hans'; // Simplified Chinese

For a complete list of all supported locales with import examples, see Supported Locales.

Supported Timezones

Complete IANA timezone database support. Pass an IANA timezone name string directly to any function:

format(new Date(), 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
format(new Date(), 'YYYY-MM-DD HH:mm:ss', { timeZone: 'America/New_York' });

For a complete list of all supported timezones, see Supported Timezones.

Numeral Systems

Support for different numeral systems:

import arab from 'date-and-time/numerals/arab';   // Arabic-Indic
import beng from 'date-and-time/numerals/beng';   // Bengali
import mymr from 'date-and-time/numerals/mymr';   // Myanmar
import latn from 'date-and-time/numerals/latn';   // Latin (default)

format(new Date(), 'DD/MM/YYYY', { numeral: arab });
// => ٠٨/٠٧/٢٠٢٥

Error Handling

Parse Failures

import { parse, isValid } from 'date-and-time';

// Always check validity first
if (!isValid('invalid-date', 'YYYY-MM-DD')) {
  throw new Error('Invalid date format');
}

// Or check parse results
const result = parse('invalid-date', 'YYYY-MM-DD');
if (isNaN(result.getTime())) {
  throw new Error('Parse failed');
}

Type Safety

import { format, FormatterOptions } from 'date-and-time';

// TypeScript will catch type errors
const options: FormatterOptions = {
  locale: 'invalid',  // ❌ TypeScript error
  timeZone: 123       // ❌ TypeScript error
};

Performance Tips

1. Use compile() for repeated operations:

   const pattern = compile('YYYY-MM-DD HH:mm:ss');
   // Reuse pattern for better performance

2. Import only what you need:

   import { format } from 'date-and-time';  // ✅ Tree-shakable
   import * as date from 'date-and-time';  // ❌ Imports everything

Migration from v3.x

If you're migrating from version 3.x, see the Migration Guide for detailed upgrade instructions and breaking changes.