web / lib/utils/timezone
lib/utils/timezone
Timezone conversion utilities using the built-in Intl API.
Provides functions to convert between IANA timezones and UTC for scheduled ingest scheduling. Uses Intl.DateTimeFormat exclusively (no external timezone libraries) to keep the dependency footprint small.
Interfaces
DateParts
The shape returned by date-part extraction functions.
Properties
year
year:
number
month
month:
number
day
day:
number
hour
hour:
number
minute
minute:
number
second
second:
number
dayOfWeek
dayOfWeek:
number
Functions
isValidTimezone()
isValidTimezone(
timezone):boolean
Validate that a string is a valid IANA timezone identifier.
Uses Intl.DateTimeFormat which throws RangeError for invalid timezones.
Parameters
timezone
string
Returns
boolean
createTimezoneFormatter()
createTimezoneFormatter(
timezone):DateTimeFormat
Create a reusable Intl.DateTimeFormat for the given timezone.
This avoids the overhead of constructing a new formatter on every call, which is critical when iterating minute-by-minute (e.g. cron matching).
Parameters
timezone
string
Returns
DateTimeFormat
getDatePartsInTimezone()
getDatePartsInTimezone(
utcDate,timezone):DateParts
Get the individual date/time components of a UTC Date as they appear in the given IANA timezone.
For example, 2024-01-15T23:30:00Z in “Europe/Berlin” (UTC+1 in winter) returns { year: 2024, month: 1, day: 16, hour: 0, minute: 30, … } because it is already January 16 00:30 in Berlin.
Parameters
utcDate
Date
timezone
string
Returns
getDatePartsWithFormatter()
getDatePartsWithFormatter(
utcDate,formatter):DateParts
Fast version of getDatePartsInTimezone that reuses a pre-created formatter.
Use this in tight loops (e.g. cron matching) where the same timezone is checked for many different dates.
Parameters
utcDate
Date
formatter
DateTimeFormat
Returns
wallClockToUtc()
wallClockToUtc(
year,month,day,hour,minute,timezone):Date
Convert a wall-clock time in a given timezone to the equivalent UTC Date.
Given a set of date/time components that represent a wall-clock time in the specified timezone, returns the corresponding UTC Date.
This uses a binary-search approach: we start with an initial UTC guess (treating the components as if they were UTC), then adjust based on the observed offset.
Parameters
year
number
month
number
day
number
hour
number
minute
number
timezone
string
Returns
Date