API Reference

All functions accept flexible date inputs and return timestamps (milliseconds since Unix Epoch).

typescript

type DateInput = number | string | Date;

Parsing

Function	Description
`now()`	Current timestamp
`parse(string)`	Parse ISO 8601 string
`tryParse(string)`	Safe parse, returns `null` on failure
`parseFormat(string, pattern)`	Parse with custom format
`tryParseFormat(string, pattern)`	Safe parse with format
`fromComponents(obj)`	Create from `{ year, month, day, ... }`

typescript

now();                                    // 1732982400000
parse('2025-11-30T12:00:00Z');           // 1732968000000
tryParse('invalid');                      // null
parseFormat('12/25/2025', 'MM/dd/yyyy'); // 1735084800000
fromComponents({ year: 2025, month: 12, day: 25 });

Parse Format Tokens

Token	Description	Example
`yyyy`	4-digit year	2025
`yy`	2-digit year	25
`MM`	2-digit month	01-12
`M`	Month	1-12
`dd`	2-digit day	01-31
`d`	Day	1-31
`HH`	24h hour	00-23
`hh`	12h hour	01-12
`mm`	Minute	00-59
`ss`	Second	00-59
`SSS`	Millisecond	000-999
`A`	AM/PM	AM, PM

Formatting

Function	Description
`format(date, pattern)`	Format with pattern
`formatUTC(date, pattern)`	Format in UTC
`formatInTimezone(date, pattern, tz)`	Format in timezone
`toISOString(date)`	ISO 8601 string
`formatDate(date)`	`yyyy-MM-dd`
`formatDateTime(date)`	`yyyy-MM-dd HH:mm:ss`

typescript

format(date, 'yyyy-MM-dd');              // "2025-11-30"
format(date, 'MMMM d, yyyy');            // "November 30, 2025"
format(date, 'EEEE');                    // "Sunday"
formatUTC(date, 'HH:mm:ss');             // "20:00:00"
formatInTimezone(date, 'HH:mm', 'Asia/Tokyo');
toISOString(date);                       // "2025-11-30T12:00:00.000Z"

Format Tokens

Token	Output	Description
`yyyy`	2025	4-digit year
`yy`	25	2-digit year
`MMMM`	November	Full month (localized)
`MMM`	Nov	Short month (localized)
`MM`	11	2-digit month
`M`	N	Single letter
`dd`	30	2-digit day
`d`	30	Day
`EEEE`	Sunday	Full day (localized)
`EEE`	Sun	Short day (localized)
`EE`	Su	2-char day
`E`	S	1-char day
`HH`	14	24h hour (2-digit)
`H`	14	24h hour
`hh`	02	12h hour (2-digit)
`h`	2	12h hour
`mm`	30	Minute
`ss`	45	Second
`SSS`	123	Millisecond
`A`	PM	AM/PM
`aa`	pm	am/pm

Escape text: 'literal' or [literal]

typescript

format(date, "'Today:' EEEE"); // "Today: Sunday"

Getters

Function	Returns
`getYear(date)`	Year (e.g., 2025)
`getMonth(date)`	Month 1-12
`getDate(date)`	Day of month 1-31
`getDay(date)`	Day of week 0-6 (Sun-Sat)
`getHours(date)`	Hours 0-23
`getMinutes(date)`	Minutes 0-59
`getSeconds(date)`	Seconds 0-59
`getMilliseconds(date)`	Milliseconds 0-999
`getDaysInMonth(date)`	Days in month (28-31)
`getComponents(date)`	All components object

typescript

getYear(date);       // 2025
getMonth(date);      // 11
getDaysInMonth(date); // 30
getComponents(date); // { year: 2025, month: 11, day: 30, ... }

Arithmetic

Function	Description
`add(date, n, unit)`	Add time
`subtract(date, n, unit)`	Subtract time
`addDays(date, n)`	Add days
`addWeeks(date, n)`	Add weeks
`addMonths(date, n)`	Add months
`addYears(date, n)`	Add years
`addHours(date, n)`	Add hours
`addMinutes(date, n)`	Add minutes
`addSeconds(date, n)`	Add seconds
`subDays(date, n)`	Subtract days
`subWeeks(date, n)`	Subtract weeks
`subMonths(date, n)`	Subtract months
`subYears(date, n)`	Subtract years
`subHours(date, n)`	Subtract hours
`subMinutes(date, n)`	Subtract minutes
`subSeconds(date, n)`	Subtract seconds

typescript

addDays(date, 7);
addMonths(date, 3);
add(date, 2, 'week');
subtract(date, 1, 'year');

Comparisons

Function	Description
`isBefore(date1, date2)`	date1 < date2
`isAfter(date1, date2)`	date1 > date2
`isSame(date1, date2, unit)`	Same unit?
`isSameDay(date1, date2)`	Same day?
`isSameMonth(date1, date2)`	Same month?
`isSameYear(date1, date2)`	Same year?

typescript

isBefore(date1, date2);       // true/false
isSame(date1, date2, 'month'); // true/false
isSameDay(date1, date2);       // true/false

Predicates

Function	Description
`isValid(date)`	Valid timestamp?
`isToday(date)`	Today?
`isTomorrow(date)`	Tomorrow?
`isYesterday(date)`	Yesterday?
`isPast(date)`	In the past?
`isFuture(date)`	In the future?
`isWeekend(date)`	Saturday or Sunday?
`isLeapYear(date)`	Leap year?

typescript

isToday(date);    // true
isWeekend(date);  // false
isLeapYear(date); // false

Boundaries

Function	Description
`startOf(date, unit)`	Start of unit
`endOf(date, unit)`	End of unit
`startOfDay(date)`	00:00:00.000
`endOfDay(date)`	23:59:59.999
`startOfWeek(date)`	Start of week
`endOfWeek(date)`	End of week
`startOfMonth(date)`	First of month
`endOfMonth(date)`	Last of month
`startOfYear(date)`	Jan 1
`endOfYear(date)`	Dec 31

typescript

startOfDay(date);        // 2025-11-30 00:00:00.000
endOfMonth(date);        // 2025-11-30 23:59:59.999
startOf(date, 'year');   // 2025-01-01 00:00:00.000

Differences

Function	Description
`diff(date1, date2, unit)`	Difference in unit
`diffInDays(date1, date2)`	Difference in days
`diffInWeeks(date1, date2)`	Difference in weeks
`diffInMonths(date1, date2)`	Difference in months
`diffInYears(date1, date2)`	Difference in years
`diffInHours(date1, date2)`	Difference in hours
`diffInMinutes(date1, date2)`	Difference in minutes
`diffInSeconds(date1, date2)`	Difference in seconds

typescript

diffInDays(date1, date2);   // 30
diff(date1, date2, 'week'); // 4

Relative Time

Function	Description
`formatDistance(date, base?, suffix?)`	Human-readable distance
`formatDuration(ms)`	Duration string

typescript

formatDistance(pastDate, now(), true);  // "2 hours ago"
formatDistance(futureDate, now(), true); // "in 3 days"
formatDuration(3600000);                 // "1h 0m 0s"

Timezone

Function	Description
`getTimezone()`	Device timezone ID
`getTimezoneOffset()`	Offset in minutes
`getTimezoneOffsetForTimestamp(date)`	Offset at date
`toTimezone(date, tz)`	Convert to timezone
`toUTC(date)`	Convert to UTC
`getAvailableTimezones()`	All timezone IDs
`isValidTimezone(tz)`	Valid timezone?

typescript

getTimezone();                    // "America/New_York"
toTimezone(date, 'Asia/Tokyo');
getAvailableTimezones();          // ["Africa/Abidjan", ...]
isValidTimezone('Europe/London'); // true

Locale

Uses native APIs for localization:

iOS: NSLocale, NSDateFormatter
Android: java.util.Locale, DateFormatSymbols

Function	Description
`getLocale()`	Current locale code
`setLocale(code)`	Set locale
`getAvailableLocales()`	Available locales object
`getLocaleDisplayName(code)`	Display name in English
`getLocaleInfo(code)`	Full locale info
`getAvailableLocalesInfo()`	All locales with info

typescript

getLocale();              // "en"
setLocale('es');          // true
getLocaleDisplayName('ja'); // "Japanese"
getLocaleInfo('pt_BR');
// { code: 'pt_BR', languageCode: 'pt', displayName: 'Portuguese (Brazil)', ... }

TIP

If setLocale() is never called, the device's default locale is used.

Utilities

Function	Description
`clamp(date, min, max)`	Clamp to range
`min(dates[])`	Earliest date
`max(dates[])`	Latest date

typescript

clamp(date, minDate, maxDate);
min([date1, date2, date3]);
max([date1, date2, date3]);

Async Batch

Process large arrays without blocking UI.

Function	Description
`parseManyAsync(strings[])`	Parse array of strings
`formatManyAsync(dates[], pattern)`	Format array of dates
`getComponentsManyAsync(dates[])`	Get components array

typescript

const timestamps = await parseManyAsync(['2025-01-01', '2025-02-15']);
const formatted = await formatManyAsync(timestamps, 'MMMM d');

Chainable API

Immutable, fluent interface similar to Day.js.

typescript

import { nativeDate } from '@bernagl/react-native-date';

nativeDate()
  .addDays(7)
  .startOfMonth()
  .format('yyyy-MM-dd');

// Properties
nativeDate().year;        // 2025
nativeDate().month;       // 11
nativeDate().date;        // 30
nativeDate().timestamp;   // milliseconds

// Methods (return new instance)
.add(n, unit)
.subtract(n, unit)
.addDays(n) / .subDays(n)
.addMonths(n) / .subMonths(n)
.startOf(unit) / .endOf(unit)
.setYear(n) / .setMonth(n) / .setDate(n)
.clone()

// Terminal methods (return values)
.format(pattern)
.toISOString()
.valueOf()
.toDate()
.isBefore(date)
.isAfter(date)
.isToday()

Types

typescript

type TimeUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';

type DateComponents = {
  year: number;
  month: number;       // 1-12
  day: number;         // 1-31
  hour: number;        // 0-23
  minute: number;      // 0-59
  second: number;      // 0-59
  millisecond: number; // 0-999
  dayOfWeek: number;   // 0-6 (Sun-Sat)
};

type LocaleInfo = {
  code: string;
  languageCode: string;
  regionCode: string;
  displayName: string;
  nativeName: string;
};

type DateInput = number | string | Date;

API Reference ​

Parsing ​

Parse Format Tokens ​

Formatting ​

Format Tokens ​

Getters ​

Arithmetic ​

Comparisons ​

Predicates ​

Boundaries ​

Differences ​

Relative Time ​

Timezone ​

Locale ​

Utilities ​

Async Batch ​

Chainable API ​

Types ​

API Reference

Parsing

Parse Format Tokens

Formatting

Format Tokens

Getters

Arithmetic

Comparisons

Predicates

Boundaries

Differences

Relative Time

Timezone

Locale

Utilities

Async Batch

Chainable API

Types