dutyDayFor

Signature

dutyDayFor(instant: string, day: DutyDay): Interval | null

Return the operator-designated day an instant falls in: from the most recent dayStartTime in timeZone at or before the instant, up to (not including) the next one.

• The day an hours-of-work rule counts is the operator’s, not the local midnight where the person happens to be, so the reference zone and the start time are both the caller’s and neither has a default.
• A dayStartTime that a clock change skips or repeats is resolved under day.disambiguation, the CORE-4 policy in resolveLocal. The default, "compatible", reads a skipped time after the gap (02:30 on New York’s spring-forward day is 03:30) and a repeated one at its first pass. The day that holds the change is then shorter or longer by the change: 23 or 25 hours across a one-hour change, 24.5 across Lord Howe’s 30-minute fall-back, 21 across Casey’s three-hour jump. "reject" returns null for a day that starts or ends at such a time.
• The instant is read in timeZone whatever offset or zone it is written with, so a log whose entries cross zones still falls into the reference zone’s days.
• A date whose start resolves onto the next date’s start opens no day: the date Pacific/Apia deleted in 2011 is part of no operator day.
• Returns null when instant is not an ISO 8601 instant string, when day is not an object with a valid timeZone and a dayStartTime that isValidTime accepts, and when the day or the next one starts outside Temporal’s instant range.

Parameters

Parameter	Type	Description
instant	string	ISO 8601 instant string to place
day	DutyDay	the reference zone and the local time each day starts at

Returns

{ start, end } of the day as UTC instants ending in “Z”, or null on invalid input

Types

DutyDay

The operator-designated day: a 24-hour period that starts at dayStartTime in timeZone, wherever the person is. Neither field has a default, and local midnight is never assumed. A day with a clock change inside it is shorter or longer by the change: 23 or 25 hours across a one-hour change.

import type { DutyDay } from "@northguild/gmt";

Member	Type	Description
timeZone	string	The reference time zone the day is read in, an IANA name or UTC offset: a time zone identifier (+05:30, +0530, -08) or a stored offset (±HH:MM[:SS], what getTimeZoneOffset returns). A log whose entries cross zones is still read in this one.
dayStartTime	string	The local wall time each day starts at, as an ISO PlainTime string ("04:00") that isValidTime accepts.
disambiguation?	"compatible" | "earlier" | "later" | "reject" (Disambiguation)	How a day start the clock repeats or skips becomes an instant, as resolveLocal resolves it. "compatible" reads a skipped time after the gap and a repeated one at its first pass, "earlier" and "later" take that side in both cases, and "reject" returns the sentinel for a day that starts or ends at such a time.

Related types

• Disambiguation
• Interval

Examples

import { dutyDayFor } from "@northguild/gmt/duty/calculate";

dutyDayFor("2024-01-01T08:59:00Z", { timeZone: "America/New_York", dayStartTime: "04:00" }) // { start: "2023-12-31T09:00:00Z", end: "2024-01-01T09:00:00Z" } — 03:59 local is the previous day

instantday

output

 

Source

duty/calculate/dutyDayFor.ts