A command-line date calculator. Get the duration between two dates, the duration between a date and today, or the date a number of days away.
npm install datecalFor global CLI access:
npm install -g datecaldatecal <date> [date | days]
datecal <days>| Arguments | Result |
|---|---|
| Two dates | Duration between the dates (e.g. 2 months 29 days) |
| One date | Duration between the date and today |
| One date and a number | The date that many days after (or before, if negative) the date |
| One number | The date that many days from today (datecal 8, datecal -8) |
A bare number is always a day offset from today, exactly as in 1.x. To
name a month by its number, use the _ sigil: _8 is August 1 and 8_ is
August 31.
Dates can be written in a stringed syntax or a digit syntax:
| Format | Example | Notes |
|---|---|---|
| Month name, date, year | "August 24 2026" |
Quotes required only when passing two dates |
| Abbreviated month | Aug. 24 26 |
Abbreviation ends with a period; year can be 2 or 4 digits |
| Digits with separators | 8-24-26, 8/24/2026, 08.24.26 |
Order is month, date, year; any of , . ; : ' - _ @ # \ / + separate |
| Ordinal dates | "20th 26 August" |
Ordinals and 4-digit years let parts appear in any order |
| Month only | August, _August, _8 |
Implies the 1st of the month; digit months require the leading _ sigil |
| Month with end specifier | 8_, August_, Auguste, August e |
Implies the last day of the month (30/31, and 28 or 29 for February on leap years) |
Omitted years imply the current year. Two-digit years resolve to the 2000s.
The sigil rule is strict: a leading or trailing _ is a month sigil
only when the token contains no other separator character. _ remains a
valid interior separator, so 8_24_26 parses as a full date, while
_8_24_26 and 8_24_26_ are errors. The digit end-of-month form 8:e was
removed; use 8_ or the word forms instead.
# Today is August 14, 2026
datecal "August 24 2026" "November 22 2026"
# 2 months 29 days
datecal 8-24-26 11-22-26
# 2 months 29 days
datecal -d 8-24-26 11-22-26
# 90 days
datecal -m 8-24-26 11-22-26
# 2.94 months
datecal -y 8-24-26 11-22-26
# 0.25 years
datecal 08-24-1926 11-22-26
# 100 years 2 months 29 days
datecal -y 08-24-1926 11-22-26
# 100.25 years
datecal August 24 2026
# 10 days
datecal 8
# August, 22 2026 (8 days from today)
datecal -8
# August, 06 2026 (8 days before today)
datecal _8
# 13 days (duration until August 1)
datecal 8_
# 17 days (duration until August 31)
datecal Auguste
# 17 days
datecal 8-24-26 90
# November, 22 2026
datecal 100
# November, 22 2026| Option | Description |
|---|---|
-v, --verbose |
Always print years, months, and days (e.g. 0 years 2 months 29 days) |
-d, --days |
Print durations in whole days (e.g. 90 days) |
-m, --months |
Print durations in months; under a whole month a two-decimal value is used (e.g. 0.25 months) |
-y, --years |
Print durations in years; under a whole year a two-decimal value is used (e.g. 100.25 years) |
-V, --version |
Print the version number |
-h, --help |
Show usage help |
-- |
Treat every following argument as a date or number |
Like --verbose, the unit flags only shape duration output and are ignored
when the result is a date. A unit flag takes precedence over --verbose, and
when several unit flags are given the last one wins. Fractions are
calendar-aware: the leftover days are measured against the actual month or
year they fall in, so 7 days is 0.25 months in a 28-day February but
0.24 months in a leap one. Days never need fractions, because dates differ
by whole days.
import { dateCal } from "datecal";
dateCal("8-24-26", "11-22-26"); // "2 months 29 days"
dateCal("August 24 2026"); // duration from today, e.g. "10 days"
dateCal("8-24-26", 90); // "November, 22 2026"
dateCal(10); // the date 10 days from today
dateCal("8-24-26", "11-22-26", { unit: "months" }); // "2.94 months"The main entry point. Behavior depends on the arguments:
| Call | Returns |
|---|---|
dateCal(days: number) |
Date days from today, formatted "Month, DD YYYY" |
dateCal(date: string) |
Duration between the date and today |
dateCal(from: string, to: string) |
Duration between the two dates |
dateCal(from: string, days: number) |
Date days after from, formatted "Month, DD YYYY" |
The dateCal(days: number) calculation is delegated to the
daycal package, the canonical home of
the day-offset calculation. When the today option is passed, the date is
computed locally instead, because daycal takes no reference-date override --
the option is honored either way.
Note that a bare integer string (dateCal("8")) is not a date and throws:
pass day offsets as numbers, and name months with the _8 / 8_ sigils.
Options (last argument):
| Option | Type | Description |
|---|---|---|
verbose |
boolean |
Always include years, months, and days in duration output |
today |
Date | CalendarDate |
Reference date used as "today" (defaults to the system date) |
unit |
"days" | "months" | "years" |
Report durations in a single unit; months and years use a two-decimal fraction below a whole unit. Takes precedence over verbose |
Throws: DateCalError when a date expression cannot be parsed or is invalid
(unknown month, day outside the month's length, illegal separator, or an
ambiguous date).
| Export | Signature | Description |
|---|---|---|
parseDate |
(expression: string, today?) => CalendarDate |
Parse a date expression into { year, month, day } |
diffDates |
(a, b) => Duration |
Calendar duration between two dates as { years, months, days } |
addDays |
(date: CalendarDate, days: number) => CalendarDate |
Add or subtract whole days |
formatDate |
(date) => string |
Format as "Month, DD YYYY" |
formatDuration |
(duration, verbose?) => string |
Format a duration, dropping leading zero groups unless verbose |
daysInMonth |
(month, year) => number |
Days in a month, leap-year aware |
isLeapYear |
(year) => boolean |
Leap year check |
import { parseDate, diffDates, formatDuration } from "datecal";
const from = parseDate("August 24 2026");
const to = parseDate("November 22 2026");
formatDuration(diffDates(from, to)); // "2 months 29 days"Durations drop leading zero groups by default:
10 days
2 months 29 days
100 years 2 months 29 days
With --verbose (or verbose: true), all three groups always print. With a
unit flag (or the unit option), the duration prints in that single unit,
using a two-decimal fraction for months and years below a whole unit
(0.25 years). Dates are returned in the Month, DD YYYY format
(e.g. November, 22 2026).
The 1.x behavior for bare numbers is restored: every bare integer is a day
offset from today again, so datecal 8 prints the date 8 days away. The 2.0.0
reading of a single number 1-12 as a month is gone.
To name a month by number, use an explicit sigil: _8 for August 1 and 8_
for August 31 (leap-aware for February). The sigils also work on names
(_August, August_). A leading or trailing _ is a sigil only on a token
with no other separator, so 8_24_26 still parses as a full date while
_8_24_26 and 8_24_26_ are errors.
The digit end-of-month form 8:e is removed; use 8_ or the word forms
(Auguste, August e), which are unchanged.
npm run build # compile TypeScript to dist/
npm test # build and run all test suites
npm run test:unit # unit tests only
npm run test:integration # CLI integration tests only
npm run test:regression # 1.x behavior regression tests onlyMIT
