📅 Date Calculator

🔧 Operation

📅 Base date

⏳ Duration

Order: years first, then months (with day-of-month clamp), then weeks & days as a flat day count. Negative components are accepted. At least one component must be non-zero.

🗓️ Business days (signed)

Positive walks forward, negative walks backward. Saturdays and Sundays are skipped (no public-holiday calendar applied).

📤 Result

{{ outputPrimary }}

📏 Resulting date

Base date
{{ activeResult.base.isoDate }} ({{ activeResult.base.dayOfWeek }})
ISO date
{{ outputResultIso }}
Day of week
{{ outputResultDow }}
Total days added
{{ activeResult.totalDaysAdded.toLocaleString() }}
Business days
{{ activeResult.daysAdded.toLocaleString() }}
Weekends skipped
{{ activeResult.weekendsSkipped.toLocaleString() }}
Calendar days shifted
{{ activeResult.totalCalendarDaysShifted.toLocaleString() }}
⚠️

ℹ️ About Date Calculator

What this calculator does

The Date Calculator shifts a base date by an explicit duration and returns the resulting date together with the day of the week and the total number of calendar days moved. Three modes are exposed; each uses the same proleptic Gregorian calendar and the same UTC arithmetic so results never drift with the user's local time zone or daylight-saving rules.

  • Add duration — add integer years, months, weeks, and days to the base date. Returns the resulting date, day of the week, total days added, and the input breakdown.
  • Subtract duration — same payload, applied in reverse. Negative duration components are accepted, so subtracting -1 year is equivalent to adding 1 year.
  • Add business days — shifts the base date by a signed integer number of weekdays, skipping Saturday and Sunday. Reports the resulting date, weekends skipped, and total calendar days walked.

How the calendar arithmetic is applied

For Add and Subtract, the operation order is deliberate: years first, then months (with day-of-month clamp), then weeks and days as a flat day count. The clamp rule keeps month addition consistent with calendar lengths: Jan 31 + 1 month becomes Feb 28 (or Feb 29 in a leap year), never March 3. 

// Pseudo-code for the calendar shift
totalMonths = years * 12 + months
newYear, newMonth = base.year, base.month shifted by totalMonths
clampedDay = min(base.day, daysInMonth(newYear, newMonth))
shifted = makeUtcDate(newYear, newMonth, clampedDay)
shifted += weeks * 7 + days   // raw day delta

This mirrors the "constrained overflow" mode documented in the Temporal.PlainDate proposal and the standard month-arithmetic convention in Reingold & Dershowitz, Calendrical Calculations, 3rd edition, §2.6.

Worked addition example

Base date 2026-05-27 with duration 1 year, 2 months, 3 weeks, 4 days:

  • 2026-05-27 + 1 year → 2027-05-27
  • 2027-05-27 + 2 months → 2027-07-27
  • 2027-07-27 + 3 weeks + 4 days = 2027-07-27 + 25 days → 2027-08-21 (Saturday)
  • Total calendar days added: 451.

The day count is computed directly from (Date.UTC(2027, 7, 21) - Date.UTC(2026, 4, 27)) / 86400000 in a Node REPL.

Business-day mode

Business days are Monday through Friday in UTC, with no public-holiday calendar. The algorithm walks the calendar one day at a time in the sign direction of the input; weekend days (Saturday, Sunday) are walked over without counting against the target. The result reports both the number of weekend days skipped and the total calendar days shifted.

  • 2026-05-29 (Friday) + 1 business day → 2026-06-01 (Monday), 2 weekends skipped, 3 calendar days shifted.
  • 2026-05-25 (Monday) + 5 business days → 2026-06-01 (Monday), 2 weekends skipped, 7 calendar days shifted.
  • 2026-05-25 (Monday) − 5 business days → 2026-05-18 (Monday), 2 weekends skipped, 7 calendar days shifted.
  • 0 business days → the base date is returned unchanged, regardless of whether the base date itself is a weekend.

Use cases

  • Project deadlines — push a milestone forward by 5 business days for review cycles.
  • Contracts and renewals — calculate end dates for fixed terms (30 days, 90 days, 1 year, 24 months).
  • Billing cycles — bill on the same day each month while respecting calendar month length.
  • Travel and leave planning — count weekdays between trip planning and departure.
  • Personal milestones — find "one year from today" or "180 days from now".

Limitations

Business days are counted strictly as Monday-Friday in UTC. No public-holiday calendar is applied — a stretch of weekdays that includes a regional holiday will still be counted. The tool also works on dates only: it does not model time of day, time zones, leap seconds, or daylight-saving transitions. For legal or payroll deadlines that depend on these factors, confirm whether the applicable rule counts endpoints, weekends, and holidays differently.

Calendar definition

All arithmetic uses the proleptic Gregorian calendar (modern leap-year rule extended backward) and is performed with Date.UTC + setUTCFullYear internally, so the same input always produces the same output regardless of timezone or DST. Years from -9999 through 9999 are supported. Invalid calendar dates such as February 30 are rejected instead of being silently rolled over. Duration components are bounded to [-1000, 1000] each for Add/Subtract, and the business-day shift is bounded to [-100000, 100000] to guard against runaway loops.

References

API Usage Example:

POST /api/tools/time/date-calculator
Content-Type: application/json

{
    "operation": "add",
    "year": 2026,
    "month": 5,
    "day": 27,
    "years": 1,
    "months": 2,
    "weeks": 3,
    "days": 4
}
Ready