- Docs
- Date tools
Date tools
Read, format, change, compare and measure dates with @samline/formatter/date: tokens, parsing, time zones, weeks and durations on native Date and Intl.
format() masks a date while people type it. @samline/formatter/date does everything after that: read the text into a Date, check it, move it, compare it, measure it and show it again in any pattern, locale or time zone. It runs on the native Date and Intl APIs with no dependencies.
import { addDate, diffDate, formatDatePattern, parseDate } from '@samline/formatter/date'
const checkIn = parseDate('24/12/2026', { format: 'DD/MM/YYYY' })
const checkOut = addDate(checkIn, 3, 'day')
diffDate(checkOut, checkIn, 'day') // 3
formatDatePattern(checkOut, 'dddd D [de] MMMM', { locale: 'es-MX' }) // 'domingo 27 de diciembre'
Every function is a separate export, so a bundle only carries what it imports: formatDatePattern alone is about 3.5 KB gzip, addDate with diffDate about 2 KB, and every function together under 10 KB. The browser builds add them as window.Formatter.date with the date add-on.
Rules shared by every function
- Inputs. Every function takes a
Date, a timestamp in milliseconds or a string. ISO strings without an offset ('2026-11-12','2026-11-12 09:30') are a wall clock in the time zone you pass, or the local one; impossible days such as'2026-02-30'are invalid. Strings withZor an offset are exact instants. - Nothing is changed in place. Functions that return a date return a new
Date. - Months are 1–12 everywhere: in
getDateParts,createDate,setDateUnitand theMtoken. - Invalid input never prints
Invalid Date. Formatting returns''fornull,undefinedand'', andfallback(default'') for unreadable values. Functions that return a date return an invalidDate, numbers areNaN, and checks arefalse. Invalid options, such as an unknown time zone, throw likeIntldoes. - Options. Most functions take
{ timeZone, locale, weekStart, minimalDays }.timeZoneis any IANA zone ('America/Cancun','UTC') and defaults to the runtime zone.localegives names and week rules and defaults to the runtime locale. - Units are
'year','quarter','month','week','isoWeek','day','hour','minute','second'and'millisecond'. The plural ('days') is accepted too.
Reading dates
parseDate(value, options?)
Returns a Date, or undefined when the value cannot be read: wrong form, an impossible day or time, or text left over in strict mode. There is no error object (@samline/date returned { isValid: false, error }), so check the result before using it:
const date = parseDate(input.value, { format: 'YYYY-MM-DD' })
if (!date) return 'Type a real date as YYYY-MM-DD.'
parseDate('2026-11-12') // local midnight, November 12
parseDate('12/11/2026', { format: 'DD/MM/YYYY' }) // November 12, 2026
parseDate('31/02/2026', { format: 'DD/MM/YYYY' }) // undefined
parseDate('5 de marzo de 2026', { format: 'D [de] MMMM [de] YYYY', locale: 'es-MX' }) // March 5, 2026
parseDate('March 5th, 2026 3:30 PM', { format: 'MMMM Do, YYYY h:mm A', locale: 'en-US' })
parseDate('2026-11-12 09:00', { timeZone: 'America/Cancun' }) // 09:00 in Cancún
| Option | Default | Meaning |
|---|---|---|
format |
none | Tokens the text is written in, or a list to try in order. Without it, Date values, timestamps and ISO strings are read. |
strict |
true |
Every number at its full width (DD is two digits), separators exactly as written and nothing left over. false accepts 1/2/2026 for DD/MM/YYYY and any separator. |
locale |
runtime | Language of month, weekday and AM/PM names. Names match ignoring case, accents and dots. |
timeZone |
local | Zone of the wall clock read. Ignored when the text has an offset (Z, ZZ). |
Missing parts are filled the way people expect: 'HH:mm' alone is that time today, a year alone is January 1. Impossible dates and times (31/02, 25:00, 13:00 PM) are rejected, and in strict mode so is a wall time skipped by a daylight-saving jump.
Localized tokens (L, LL…), week tokens and time-zone names are output only.
Matching a masked input
A date field formatted with datePattern: ['d', 'm', 'Y'] and the / delimiter shows DD/MM/YYYY. Read it with the same tokens:
import { format } from '@samline/formatter'
import { isValidDate, parseDate } from '@samline/formatter/date'
const { formatted } = format(input.value, 'date', { datePattern: ['d', 'm', 'Y'], delimiter: '/' })
const date = parseDate(formatted, { format: 'DD/MM/YYYY' })
The pattern letters map to tokens: d → DD, m → MM, Y → YYYY, y → YY.
isValidDate(value, options?)
true when parseDate with the same options returns a date. A Date object is valid when its time is a number.
isValidDate('29/02/2024', { format: 'DD/MM/YYYY' }) // true
isValidDate('29/02/2025', { format: 'DD/MM/YYYY' }) // false
Showing dates
formatDatePattern(value, pattern?, options?)
const date = parseDate('2026-11-12 15:04')
formatDatePattern(date, 'DD/MM/YYYY') // '12/11/2026'
formatDatePattern(date, 'MMMM D, YYYY', { locale: 'en-US' }) // 'November 12, 2026'
formatDatePattern(date, 'dddd, D [de] MMMM [de] YYYY', { locale: 'es-MX' }) // 'jueves, 12 de noviembre de 2026'
formatDatePattern(date, 'h:mm A', { locale: 'en-US' }) // '3:04 PM'
formatDatePattern(date, 'LL', { locale: 'es-MX' }) // '12 de noviembre de 2026'
formatDatePattern(date, 'HH:mm z', { timeZone: 'America/Mexico_City', locale: 'en-US' })
pattern defaults to ISO 8601 with the offset ('YYYY-MM-DDTHH:mm:ssZ'). Names come from Intl, so every locale works without loading locale files. Next to a day number, months use the grammatical form the language needs ('12 ноября', but 'ноябрь 2026'). In Japanese and Chinese, MMMM and MMM keep the month counter (formatDatePattern(date, 'D MMMM YYYY', { locale: 'ja' }) → '23 3月 2026'), and parseDate reads them back, Korean 3월 included. options takes timeZone, locale, weekStart, minimalDays and fallback.
Tokens
| Token | Output | Example (Thursday, November 12, 2026, 15:04:05.678) |
|---|---|---|
YYYY / YY |
Year, four or two digits | 2026 / 26 |
Q |
Quarter | 4 |
M / MM |
Month number | 11 / 11 |
MMM / MMMM |
Month name, short or long | Nov / November |
D / DD |
Day of the month | 12 / 12 |
Do |
Day with its ordinal mark (1st, 1º, 1er, 1.) |
12th |
DDD / DDDD |
Day of the year | 316 / 316 |
d |
Weekday, 0 Sunday – 6 |
4 |
dd / ddd / dddd |
Weekday name, two letters, short or long | Th / Thu / Thursday |
E |
ISO weekday, 1 Monday – 7 |
4 |
e |
Weekday counted from the locale’s first day | 4 (en-US) |
w / ww |
Week of the year by the locale’s rules | 46 / 46 (en-US) |
W / WW |
ISO week | 46 / 46 |
gggg / GGGG |
Week-year, by the locale or ISO | 2026 / 2026 |
H / HH |
Hour, 0–23 | 15 / 15 |
h / hh |
Hour, 1–12 | 3 / 03 |
k / kk |
Hour, 1–24 | 15 / 15 |
m / mm |
Minute | 4 / 04 |
s / ss |
Second | 5 / 05 |
S / SS / SSS |
Fraction of a second | 6 / 67 / 678 |
A / a |
Localized AM/PM, upper or lower case | PM / pm |
X / x |
Unix seconds / milliseconds | 1794495845 |
Z / ZZ |
Offset from UTC | +00:00 / +0000 (UTC) |
z / zzz |
Time-zone name, short or long | CST / Central Standard Time |
LT / LTS |
Locale time, without or with seconds | 3:04 PM |
L / l |
Locale numeric date | 11/12/2026 / 11/12/2026 |
LL / ll |
Locale date with the month name, long or short | November 12, 2026 / Nov 12, 2026 |
LLL / lll |
LL with the time |
November 12, 2026 at 3:04 PM |
LLLL / llll |
LLL with the weekday |
Thursday, November 12, 2026 at 3:04 PM |
[text] |
Printed as is | [de] → de |
The L family comes from Intl.DateTimeFormat, so its exact punctuation follows the browser.
formatCalendar(value, options?)
A label for nearby days: 'Today at 3:30 PM', 'Yesterday at 9:00 AM', 'Tomorrow at 9:00 AM', the weekday for the next six days ('Monday at 9:30 AM'), and sameElse (default 'L', the numeric date) for anything else. Words and the connector come from Intl, so es-MX reads 'Mañana, 9:30 a.m.'. Takes now (default: now), sameElse, timeZone, locale and fallback.
formatRelativeTime(value, options?)
The distance from now ('hace 3 días', 'in 2 hours'). It is the same function as in @samline/formatter/intl, re-exported here.
Changing dates
addDate(value, amount, unit, options?) and subtractDate
addDate('2026-01-31', 1, 'month') // February 28, 2026
addDate('2024-02-29', 1, 'year') // February 28, 2025
addDate(date, { months: 1, days: 2, hours: 3 }) // a duration object, larger units first
subtractDate(date, 90, 'minute')
Years, quarters, months, weeks and days follow the calendar: the day stays inside a shorter month, and 09:00 stays 09:00 when daylight saving changes overnight. Hours and smaller are exact elapsed time, so addDate(date, 24, 'hour') across that night lands at 10:00. Pass timeZone to do this on another zone’s calendar.
startOfDate(value, unit, options?) and endOfDate
The first and last millisecond of the unit that contains value: startOfDate(date, 'month'), endOfDate(date, 'day'). 'week' starts on the locale’s first day (weekStart overrides it); 'isoWeek' starts on Monday. On a daylight-saving day, the day is 23 or 25 hours long.
setDateUnit(value, unit, amount, options?)
Set one part: 'year', 'quarter', 'month' (1–12), 'day', 'weekday' (0 Sunday – 6, within the same week), 'isoWeekday' (1 Monday – 7), 'dayOfYear', 'hour', 'minute', 'second' or 'millisecond'. Setting the month or year keeps the day inside the month; other values roll over ('day', 32 → the next month).
clampDate(value, min?, max?)
value kept within min and max, either of which may be omitted. Useful with an input’s dateMin and dateMax.
Comparing and measuring
diffDate(a, b, unit?, options?)
a - b in unit (default 'millisecond'), truncated toward zero unless float: true.
diffDate('2026-12-24', '2026-12-20', 'day') // 4
diffDate('2026-03-31', '2026-01-31', 'month') // 2
diffDate('2026-11-12 12:00', '2026-11-12 10:30', 'hour', { float: true }) // 1.5
Months, quarters and years are measured on the calendar (January 31 to February 28 is one month, because adding one month to January 31 gives February 28). Days and weeks count calendar days, so a 23-hour daylight-saving day is still one day.
Checks
| Function | true when |
|---|---|
isBeforeDate(a, b, unit?, options?) |
a is before b; with unit, before the whole unit of b |
isAfterDate(a, b, unit?, options?) |
a is after b; with unit, after the whole unit of b |
isSameDate(a, b, unit?, options?) |
Same instant, or same unit (isSameDate(a, b, 'day')) |
isSameOrBeforeDate / isSameOrAfterDate |
Either of the two |
isBetweenDate(value, from, to, options?) |
Between the edges, in either order. inclusivity: '()' (default), '[]', '[)', '(]'; unit compares whole units |
isToday / isTomorrow / isYesterday(value, options?) |
On that day in timeZone; now sets the reference |
isWeekend(value, options?) |
On the locale’s weekend |
isLeapYear(yearOrDate) |
A leap year |
minDate(...dates) and maxDate(...dates) return the earliest and latest valid date (or undefined); they accept dates or one array.
Calendar facts
| Function | Returns |
|---|---|
daysInMonth(value) |
28–31 |
dayOfYear(value) |
1–366 |
quarter(value) |
1–4 |
weekOfYear(value, options?) |
Week number by the locale’s rules (weekStart, minimalDays override them) |
weekYear(value, options?) |
The year that week belongs to |
isoWeek / isoWeekYear |
ISO 8601 week and week-year (Monday first; week 1 contains January 4) |
isoWeeksInYear(yearOrDate) |
52 or 53 |
getWeekInfo(locale?) |
{ firstDay, minimalDays, weekend } for the locale |
Week rules come from Intl.Locale where the browser has them and from CLDR data otherwise, so en-US and es-MX weeks start on Sunday and es-ES and de-DE weeks on Monday.
Time zones
A Date is an instant; a time zone decides which wall clock it shows. Pass timeZone to any function to read, round, change or show dates on that zone’s clock, whatever zone the visitor is in.
import { createDate, formatDatePattern, getDateParts } from '@samline/formatter/date'
// 8:00 PM on December 24 in Cancún, from any visitor's browser.
const dinner = createDate(
{ year: 2026, month: 12, day: 24, hour: 20 },
{ timeZone: 'America/Cancun' }
)
formatDatePattern(dinner, 'LLL', { timeZone: 'Europe/Madrid', locale: 'es-ES' }) // the same instant in Madrid
getDateParts(dinner, { timeZone: 'Asia/Tokyo' }) // { year: 2026, month: 12, day: 25, hour: 10, … }
| Function | Returns |
|---|---|
createDate(parts, options?) |
The instant of { year, month?, day?, hour?, minute?, second?, millisecond? } in timeZone. Out-of-range fields roll over. |
getDateParts(value, options?) |
{ year, month, day, hour, minute, second, millisecond, weekday, offset } in timeZone, or undefined |
getTimeZoneOffset(value?, options?) |
Minutes east of UTC (-360 in Mexico City, 60 in Madrid in winter) |
getTimeZone() |
The runtime’s zone, such as 'America/Mexico_City' |
fromUnix(seconds) / toUnix(value) |
Conversion from and to Unix seconds |
A wall time skipped when clocks jump forward moves forward by the jump (2:30 becomes 3:30); a repeated wall time when clocks go back resolves to the earlier instant. These are the same rules as Date and Temporal.
Durations
import {
createDuration,
durationAs,
formatDuration,
humanizeDuration,
} from '@samline/formatter/date'
formatDuration({ hours: 1, minutes: 30 }, { locale: 'es-MX' }) // '1 hora y 30 minutos'
formatDuration(5_400_000, { style: 'digital' }) // '1:30:00'
durationAs('PT1M30S', 'second') // 90
humanizeDuration({ days: 3 }, { withSuffix: true, locale: 'en-US' }) // 'in 3 days'
A duration is milliseconds, an ISO 8601 string ('P1DT2H') or an object with any of years, months, weeks, days, hours, minutes, seconds and milliseconds.
| Function | Returns |
|---|---|
createDuration(input) |
Every field filled in, or undefined. Milliseconds split into days and smaller units, never months. |
durationAs(input, unit?) |
The total in unit; months and years use the average Gregorian length (30.44 and 365.2425 days) |
durationToISO(input) |
'P1DT2H'; empty durations are 'PT0S' |
formatDuration(input, options?) |
Words in the locale, leaving out zero fields. style: 'long', 'short', 'narrow' or 'digital' (H:mm:ss). fallback for unreadable input. |
formatDurationPattern(input, pattern) |
Each field with tokens: Y, M, W, D, H/HH, m/mm, s/ss, SSS, [text] |
humanizeDuration(input, options?) |
Rounded to the largest unit ('2 hours'); withSuffix gives 'in 2 hours' or '2 hours ago' |
Add a duration with addDate(date, duration), and measure one with createDuration(diffDate(a, b)).
Browser
The date tools are an add-on to the browser builds, so pages that do not use them do not load them. Load it after formatter.global.js or formatter.phone.global.js:
<script src="https://cdn.jsdelivr.net/npm/@samline/formatter@3.3.1/dist/browser/formatter.global.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@samline/formatter@3.3.1/dist/browser/formatter.date.global.js"></script>
<script>
const { addDate, formatDatePattern } = window.Formatter.date
formatDatePattern(addDate(new Date(), 1, 'day'), 'dddd D', { locale: 'es-MX' })
</script>
The add-on is about 24 KB minified (9 KB gzip). It reuses Formatter.intl.formatRelativeTime as Formatter.date.formatRelativeTime instead of shipping it twice.
Types
Exported from @samline/formatter/date: DateInput, DateLocale, DateOptions, DateParts, DatePartsInput, DateUnit, DateSetUnit, Weekday, WeekInfo, ParseDateOptions, FormatDatePatternOptions, CalendarOptions, DiffOptions, BetweenOptions, RelativeDayOptions, ZoneOptions, Duration, DurationInput, DurationObject, DurationUnit, FormatDurationOptions and HumanizeDurationOptions.