Skip to main content

Work with dates and time zones

Send dates to the API in Coordinated Universal Time (UTC), show them to people in India Standard Time (IST), and check and calculate dates the same way in every layer.

How the package handles dates​

The package follows these rules for every date:

  • The API sends and stores dates in UTC.
  • People see dates in IST (Asia/Kolkata, +05:30) unless you pass another timezone.
  • A date-time with no zone, such as "2026-10-07 09:00:00", is read as UTC.

The package supports these time zones:

  • UTC
  • Asia/Kolkata
  • Fixed offsets, such as "+05:30"

Time zones with daylight saving time aren't supported. Neither JavaScript nor Python needs a time zone database.

Send a date to the API​

To turn a date that the user typed into the API format, use apiDate or apiDateTime, with inputFormat describing how the user typed it:

formatters("07-10-2026", "apiDate", { inputFormat: "DD-MM-YYYY" })   // "2026-10-07"

Text typed with a time is read in IST unless you set inputTimezone.

Show a stored date​

To show a stored UTC date, use displayDate or displayDateTime:

formatters("2026-10-07 09:00:00", "displayDateTime")                         // "07-10-2026 14:30"
formatters("2026-10-07 09:00:00", "displayDateTime", { timezone: "UTC" })    // "07-10-2026 09:00"
formatters("2026-10-07 09:00:00", "date", { format: "DD MMM YYYY, hh:mm A" })

A date that the package can't read formats as "". For the format tokens, see formatters().

Check a date range​

Use the date rule with date bounds:

validators(value, "date", { minDate: "today", maxDate: { addDays: 30 } })   // within the next 30 days
validators(bidEnd, "date", { after: bidStart })                             // strictly after another field
validators(value, "pastDate")                                               // not after today

minDate and maxDate include the bound, and after and before exclude it. A bound can be a date, "today", "now", { addDays: n }, or another field's value. "Today" is the calendar day in timezone, IST by default. For details, see validators().

Calculate with dates​

The date helpers count calendar days in IST by default:

helpers("2026-12-25", "addDays", { days: 10 })                         // "2027-01-04"
helpers("2026-10-01", "daysBetween", { to: "2026-10-07" })             // 6
helpers("2026-10-06 20:00:00", "daysBetween", { to: "2026-10-07" })    // 0, because 20:00 UTC on the 6th is the 7th in IST
helpers("2027-01-15", "financialYear")
// { startYear: 2026, endYear: 2027, start: "2026-04-01", end: "2027-03-31", label: "2026-27", code: "2627" }

financialYear runs from April to March unless you set startMonth.