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

Use compile() for repeated operations:

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

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.